@agentproto/apps 0.12.0 → 0.13.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentproto/apps",
-  "version": "0.12.0",
+  "version": "0.13.0",
   "description": "@agentproto/apps — a home for ready-made agentproto apps (teams of agents + their workflows), declared with @agentproto/app-kit. Import a team (code-team, content-team, …) and use any of its agents/workflows from your own host: in-process via toMastraAgents(), or emit its manifests to disk.",
   "keywords": [
     "agentproto",
@@ -59,6 +59,11 @@
       "import": "./dist/ops-panel.mjs",
       "default": "./dist/ops-panel.mjs"
     },
+    "./config": {
+      "types": "./dist/config/index.d.ts",
+      "import": "./dist/config.mjs",
+      "default": "./dist/config.mjs"
+    },
     "./session-viewer": {
       "types": "./dist/session-viewer/index.d.ts",
       "import": "./dist/session-viewer.mjs",
@@ -138,6 +143,7 @@
   },
   "files": [
     "dist",
+    "repo-maintenance",
     "README.md",
     "LICENSE"
   ],
@@ -147,8 +153,9 @@
   "dependencies": {
     "zod": "^4.6.5",
     "@agentproto/agent": "0.2.4",
-    "@agentproto/app-kit": "1.2.1",
-    "@agentproto/workflow": "0.6.1"
+    "@agentproto/app-client": "0.4.0",
+    "@agentproto/app-kit": "1.3.0",
+    "@agentproto/workflow": "0.7.0"
   },
   "peerDependencies": {
     "@mastra/core": ">=1.0.0"
@@ -156,12 +163,13 @@
   "devDependencies": {
     "@mastra/core": "1.66.0",
     "@types/node": "^25.9.5",
+    "jsdom": "^29.1.1",
     "tsup": "^8.5.1",
     "typescript": "^5.9.3",
     "vite": "^7.3.6",
     "vite-plugin-singlefile": "^2.3.0",
     "vitest": "^3.2.7",
-    "@agentproto/mastra": "0.2.14",
+    "@agentproto/mastra": "0.2.15",
     "@agentproto/tooling": "0.1.0"
   },
   "scripts": {

package/repo-maintenance/.agentproto/APP.md

@@ -0,0 +1,22 @@
+---
+schema: app/v1
+id: '@agentproto/repo-maintenance'
+name: Repo Maintenance
+version: 0.1.0
+description: >-
+  Plans and (opt-in) applies branch_gc + worktree_gc for a repo, with a
+  reviewer agent fanned out over every unmerged branch candidate before any
+  apply happens. Built on the branch_gc/branch_gc_verdict/worktree_gc tools
+  (agentproto/ts).
+agents:
+  - id: '@agentproto/repo-maintenance-reviewer'
+    path: .agentproto/agents/repo-maintenance-reviewer/AGENT.md
+workflows:
+  - id: maintain
+    path: .agentproto/workflows/maintain/WORKFLOW.md
+---
+
+Plans and (opt-in) applies branch_gc + worktree_gc for a repo, with a
+reviewer agent fanned out over every unmerged branch candidate before any
+apply happens. See README.md for how to install and run it, and
+`routines/` for the daily/weekly scheduled templates.

package/repo-maintenance/.agentproto/agents/repo-maintenance-reviewer/AGENT.md

@@ -0,0 +1,142 @@
+---
+schema: agent/v1
+id: '@agentproto/repo-maintenance-reviewer'
+description: >-
+  Reviews one stale, unmerged git branch at a time (spawned by the
+  `maintain` workflow's `review` map step) and decides whether deleting it
+  loses anything of value. Records its verdict via the branch_gc_verdict
+  tool — it never writes files and never deletes anything itself.
+model: claude-sonnet-5
+boundaries:
+  - Read-only on git — never checkout, switch, branch -d, reset, stash, commit, fetch, push, or touch a worktree
+  - Never edit, create, or delete any file in the repo
+  - Call branch_gc_verdict exactly once for the branch this turn is about, then stop
+  - agree:true only for obsolete/superseded, and only with concrete cited evidence
+  - Never merge, rebase, or otherwise mutate branch history
+tools:
+  - run_command
+  - list_dir
+  - read_file
+  - branch_gc_verdict
+workflows:
+  - ref: maintain
+---
+
+You review one stale git branch and decide whether deleting it loses
+anything of value. You are the gate: a branch only gets reclaimed later if
+you say `agree: true` in your verdict, so be conservative and cite evidence.
+
+## Hard rules
+
+- READ-ONLY on git. Allowed: `git log`, `git show`, `git diff`, `git grep`,
+  `git cat-file`, `git merge-base`, `git rev-list`, `git branch --contains`,
+  `git ls-tree`. Forbidden: anything that changes refs, the index, or the
+  working tree (no checkout, switch, branch -d, reset, stash, commit, fetch,
+  push, worktree). Do not edit any repo file. The repo path in your prompt
+  is a disposable detached worktree made for this review — the live checkout
+  is elsewhere and off limits — but the stash list and refs are shared with
+  every checkout of the repo, so the rule still holds there. Read a branch
+  through its sha: `git show <sha>:<path>`, `git ls-tree -r <sha>`.
+- Always pass `-C <repo path from the prompt>` to git, and use that same path
+  as `repoRoot` for `branch_gc_verdict`.
+- Cap output: pipe big diffs through `head -300`, or use `--stat` first.
+- Never write temp files (no `git show … > /tmp/x && diff …`). Git compares
+  revisions directly: `git diff <a>:<path> <b>:<path>` for one file across
+  two revisions (paths may differ, e.g. after a move), or
+  `git diff <a> <b> -- <path>` when the path is the same on both.
+
+## What you're given per branch
+
+`sha` (the tip), the base ref + its sha, `mergeBase`, `compareBase` (only
+set for pre-rewrite history — see below), `mergedTree` (the tree base would
+have if this branch merged cleanly, `null` when the merge conflicts),
+`coverage`, `residualFiles`, and the push state.
+
+The push state says whether a remote holds this work: `same-tip-on-remote`
+/ `contained-in-remote` (a remote ref has this tip), `diverged-from-remote`
+(a same-named remote branch exists but lacks this tip), `local-only` (no
+remote ref at all), or — for an orphan ref — `contained-elsewhere` /
+`only-copy`. A local branch whose push state is `local-only`, empty, or
+`null` is NOT recoverable from a remote, and neither is the unpushed part of
+a `diverged-from-remote` one: deleting it deletes the only copy. Never cite
+"recoverable from the remote" as evidence unless the push state is
+`same-tip-on-remote` or `contained-in-remote`.
+
+`coverage` is already computed for you, by content, before you're spawned:
+`covered` (the exact blob exists somewhere in base) and `ignored`
+(gitignored in base) files are settled — don't re-check them. `residualFiles`
+lists only what is NOT provably in base: `evolved` (same filename exists in
+base with different content — usually base kept editing a file this branch
+also touched) and `unique` (no trace in base at all: could be a build
+artifact, could be real lost work). Spend your effort on the residual files.
+
+If a `compareBase` is present, the repo's history was re-rooted after this
+branch was cut — `compareBase` is the old-history twin of the current base.
+Commit shas from that old history do not exist on the current base; compare
+by CONTENT (`git grep` on the current base, diff paths), never by sha.
+
+## Traps seen in practice
+
+- A merge-conflict residual made only of `<<<<<<<`/`>>>>>>>` markers around
+  rows base already has (ledgers, READMEs) is NOT unique content — base
+  appended more rows after this branch's row, and the branch's own row is
+  usually already there. `git grep` the row's text on base.
+- A reorg on base moves content, it doesn't delete it — before calling
+  anything "missing on base", look for the same filename elsewhere
+  (`git ls-tree -r --name-only <base> | grep /<name>`).
+- "The feature landed via PR #N" is not evidence that THIS branch's residual
+  landed. Say specifically what the evolved/unique files are and where their
+  content (or the lack of it) actually is on base.
+
+## Method
+
+1. What this branch still adds: if a merged tree is given,
+   `git diff --stat <base> <mergedTree>` then `git diff <base> <mergedTree>
+   -- <path>` per residual file. Otherwise `git diff --stat <mergeBase>
+   <sha>`. Commits: `git log --oneline <compareBase-or-base>..<sha> | head -40`.
+2. For each meaningful residual file, check whether base already has the
+   same intent under a different form: `git log --oneline -n 15 <base> --
+   <path>`, `git grep -n '<distinctive string>' <base> -- <path>`, look for
+   a squash-merge commit whose subject matches this branch's commits. To
+   compare a residual file against its counterpart on base, diff the blobs
+   in place — `git diff <base>:<path> <sha>:<path>` (or
+   `<base>:<other-path>` when base moved it) — never via a temp file.
+3. Classify:
+   - `obsolete`: dead work (abandoned experiment, reverted approach,
+     generated snapshots, lockfile-only churn, deleted-on-base files this
+     branch only tweaks).
+   - `superseded`: the intent landed on base in another form (show where).
+   - `salvage`: real unlanded work with value — code, tests, docs, or unique
+     facts in plans/ledgers/runbooks/evidence files. A unique fact counts as
+     value even if it's small.
+   - `in-progress`: active work toward something not merged yet.
+   - `unclear`: you genuinely can't tell.
+4. `agree: true` ONLY for `obsolete`/`superseded`, and only with concrete
+   evidence (a sha or path plus what it shows). Anything with a unique
+   ledger/plan/evidence entry, or real code not on base, is `agree: false`.
+   Check the push state before relying on a remote copy: an unpushed
+   (`local-only`) branch has none — see "What you're given" above.
+
+## Recording your verdict
+
+The tool is served by the agentproto MCP server — in Claude Code it shows up
+as `mcp__agentproto__branch_gc_verdict`. If your harness lists it as
+deferred, load its schema once (one tool search for that exact name), then
+call it; don't search again. Call `branch_gc_verdict` exactly once, with:
+
+```
+{
+  repoRoot: "<repo root you were given>",
+  name: "<branch name>",
+  sha: "<the exact tip sha you were given>",
+  triage: { verdict, confidence (0..1), reason, salvage? },
+  gate: { agree, verdict, reason, evidence: ["<sha or path>: what it shows", ...] },
+  reviewer: "repo-maintenance-reviewer",
+}
+```
+
+`gate.agree: true` with empty `evidence` is rejected by the tool — always
+cite at least one concrete sha or path when you agree. After the tool call
+succeeds, reply with one line: `<verdict> <agree> <name> — <reason under 20
+words>`, then stop. You do not delete the branch, and you do not need to ask
+permission to record the verdict — recording is not deleting.

package/repo-maintenance/.agentproto/workflows/maintain/WORKFLOW.md

@@ -0,0 +1,262 @@
+---
+name: Repo Maintenance
+id: maintain
+description: >-
+  Plan worktree_gc + branch_gc, fan a review agent out over up to
+  `maxReviews` unreviewed branch candidates, newest first (small model for a
+  small residual, large model otherwise), verify every candidate got a verdict, optionally apply
+  (reclaim-only) worktree/branch gc, and report — plus an agentpush
+  notification when `notify` is set. Entry-based (see entry.mjs): the
+  `review` map step's per-candidate model selector is a real run-time
+  function, which the pure-.md path cannot express (`defineWorkflow` rejects
+  a non-string `model` — "a run-time selector is only available on the
+  TS-authored runtime step").
+version: 0.1.0
+entry: ./entry.mjs
+inputs:
+  repoRoot:
+    type: string
+    description: Absolute path to the git repo. Wins over `workspaceSlug`.
+  workspaceSlug:
+    type: string
+    description: Workspace slug. The active workspace when both are omitted.
+  applyMerged:
+    type: boolean
+    description: Execute branch_gc/worktree_gc (reclaim-class only) after review.
+    default: false
+  reviewModelSmall:
+    type: string
+    description: Model for a review candidate with residualFileCount <= 3.
+    default: claude-haiku-4-5-20251001
+  reviewModelLarge:
+    type: string
+    description: Model for a review candidate with residualFileCount > 3.
+    default: claude-sonnet-5
+  maxReviews:
+    type: number
+    description: >-
+      Most review candidates to review this run — newest tip first, then the
+      larger residual. The rest are reported as not reviewed this run; tips
+      with a stored verdict are never re-reviewed, so daily runs walk the
+      backlog.
+    default: 40
+  notify:
+    type: object
+    description: >-
+      Optional agentpush `to` target ({ channel, address }) to notify with
+      the report when set. Omit for no notification.
+outputs: {}
+steps:
+  - id: worktreeGcPlan
+    kind: tool
+    name: Plan worktree gc
+    tool: worktree_gc
+    inputs:
+      repoRoot: $input.repoRoot
+      workspaceSlug: $input.workspaceSlug
+      apply: false
+
+  - id: branchGcPlan
+    kind: tool
+    name: Plan branch gc
+    tool: branch_gc
+    inputs:
+      repoRoot: $input.repoRoot
+      workspaceSlug: $input.workspaceSlug
+      apply: false
+      includeReviewed: false
+
+  - id: reviewQueue
+    kind: transform
+    name: Queue unreviewed review candidates, one per branch name
+    description: >-
+      Entry-based — no string expression language for `compute` in the
+      declarative manifest. See entry.mjs's buildReviewQueue: dedupes by tip
+      sha, then merges candidates whose refs share one branch name (a local
+      branch and its remote twin review together even when their tips
+      diverged — the newest tip is primary, the older ones ride along as
+      otherTips), skips names whose every tip already carries a stored
+      verdict, and orders oldest first, then the larger residual.
+
+  - id: reviewCandidates
+    kind: transform
+    name: Take this run's share of the queue
+    description: Entry-based — the first `maxReviews` of reviewQueue.
+
+  - id: reviewWorktreePaths
+    kind: transform
+    name: Name each candidate's disposable review worktree
+    description: >-
+      Entry-based. Every candidate carries `reviewWorktree`, a detached
+      worktree path under the OS tmp dir (`agentproto-maintain-review/`),
+      never the live checkout. This step lists them for the cleanups.
+
+  - id: review
+    kind: map
+    name: Review every unmerged branch
+    description: >-
+      One reviewer-agent turn per branch name, parallelism 4. Model is
+      picked per item by entry.mjs: haiku when residualFileCount <= 3, else
+      sonnet. The agent records its verdict via branch_gc_verdict — one call
+      PER tip the item carries (an item may hold a local + a remote tip that
+      diverged); this step never applies anything. After the turn,
+      branch_gc_verdict_get checks the store for EVERY tip; with any
+      verdict missing, the SAME session is re-prompted once, then one fresh
+      large-model reviewer retries, and only then are the still-missing tips
+      left as gaps. Each item first creates its own
+      detached review worktree of the primary tip (`branch_gc_review_worktree`),
+      runs its reviewers there — never in the live checkout — and removes it
+      last. Three spawn
+      failures in a row open the engine's circuit breaker: the remaining
+      candidates are not started and are reported as not reviewed. See
+      entry.mjs for the body.
+    over: $steps.reviewCandidates
+    parallelism: 4
+    onError: collect
+    steps:
+      - id: reviewOne
+        kind: agent
+        agent:
+          ref: "@agentproto/repo-maintenance-reviewer"
+        prompt: See entry.mjs — mustache-templated over $item + branchGcPlan.
+
+  - id: reviewCleanup
+    kind: tool
+    name: Remove every review worktree
+    description: >-
+      An item that failed never reached its own removal — clear them all
+      before anything re-plans or gc's worktrees. The entry's `finally`
+      block runs the same removal again whatever happens (failure, cancel).
+    tool: branch_gc_review_worktree
+    inputs:
+      repoRoot: $steps.branchGcPlan.plan.repoRoot
+      action: remove
+      paths: $steps.reviewWorktreePaths
+
+  - id: branchGcVerify
+    kind: tool
+    name: Re-plan to pick up recorded verdicts
+    tool: branch_gc
+    inputs:
+      repoRoot: $input.repoRoot
+      workspaceSlug: $input.workspaceSlug
+      apply: false
+      includeReviewed: false
+
+  - id: gaps
+    kind: transform
+    name: Review candidates with no recorded verdict
+    description: Entry-based — see entry.mjs's computeReviewGaps.
+
+  - id: branchGcApply
+    kind: tool
+    name: Apply branch gc (reclaim only)
+    description: >-
+      `apply` is $input.applyMerged — a dry-run plan again when false.
+      `includeReviewed` stays false: this workflow never reclaims a
+      review-class branch, even an agreed one (see the approve-reviewed
+      seam below).
+    tool: branch_gc
+    inputs:
+      repoRoot: $input.repoRoot
+      workspaceSlug: $input.workspaceSlug
+      apply: $input.applyMerged
+      includeReviewed: false
+      scopes: [local, remote, orphan]
+
+  - id: worktreeGcApply
+    kind: tool
+    name: Apply worktree gc
+    tool: worktree_gc
+    inputs:
+      repoRoot: $input.repoRoot
+      workspaceSlug: $input.workspaceSlug
+      apply: $input.applyMerged
+      salvageDirty: false
+
+  - id: report
+    kind: transform
+    name: Build the markdown summary
+    description: Entry-based — see entry.mjs's buildReport.
+
+  - id: notifyBody
+    kind: transform
+    name: Format the agentpush notification body
+    description: Entry-based — turns the report into agentpush's send_message JSON body.
+
+  - id: shouldNotify
+    kind: transform
+    name: Decide whether there's anything worth notifying about
+    description: >-
+      Entry-based — true only when `notify` is set AND there's a
+      reclaimable ref or a review candidate. A clean plan-only sweep
+      shouldn't page anyone.
+
+  - id: maybeNotify
+    kind: branch
+    name: Notify only when shouldNotify is true
+    branches:
+      - when: $steps.shouldNotify
+        next: notify
+    default: skip-notify
+
+  - id: notify
+    kind: tool
+    name: Send the agentpush notification
+    tool: command_execute
+    inputs:
+      command: bash
+      args:
+        - "-c"
+        - >-
+          curl -s --max-time 30 -X POST -H "Authorization: Bearer
+          ${AGENTPUSH_API_KEY:-}" -H "Content-Type: application/json"
+          https://api.agentpush.io/tools/send_message --data-binary @-
+      stdin: $steps.notifyBody
+
+  - id: skip-notify
+    kind: gate
+    name: No notification requested
+    command: "true"
+
+result:
+  report: $steps.report
+  gaps: $steps.gaps
+  applyMerged: $input.applyMerged
+  branchGcApply: $steps.branchGcApply
+  worktreeGcApply: $steps.worktreeGcApply
+---
+
+# Repo Maintenance — `maintain` workflow
+
+`worktree_gc` + `branch_gc` plan → fan a reviewer agent out over every
+unmerged branch (small model for a small residual, large model otherwise) →
+verify every candidate got a verdict → optionally apply (reclaim-class only)
+→ markdown report, plus an agentpush notification when `notify` is set.
+
+Entry-based (`entry.mjs`) for one reason: `review`'s per-candidate `model`
+selector is a real run-time function, which only the entry-loader path can
+carry (see the description above and entry.mjs's own docblock).
+
+## Review worktrees
+
+Reviewers never run in the live checkout. Each review item creates a
+disposable DETACHED worktree of the tip under review under the OS tmp dir
+(`branch_gc_review_worktree`, which refuses any other location) and removes
+it when the item ends; `reviewCleanup` removes them all after the map, and
+entry.mjs's `finally` block removes them once more on failure or cancel — a
+`finally` step always runs.
+
+## Out of scope, on purpose
+
+Recording a verdict via `branch_gc_verdict` never reclaims a branch by
+itself — `branchGcApply` always runs with `includeReviewed: false`. A
+human-in-the-loop gate that reclaims `review`-class branches whose stored
+verdict agreed is a documented, unwired seam (`approve-reviewed`), not built
+here — see the app README, "Out of scope: the approval gate".
+
+## Enabling
+
+`command_execute` (the `notify` step) needs `bash` allowlisted in the
+workspace's `.agentproto/allowed-commands.json`, and `AGENTPUSH_API_KEY` set
+in the daemon's environment, before passing a `notify` input.