@agentproto/apps 0.15.0 → 0.17.0

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

@@ -26,12 +26,16 @@ inputs:
     default: false
   reviewModelSmall:
     type: string
-    description: Model for a review candidate with residualFileCount <= 3.
-    default: claude-haiku-4-5-20251001
+    description: >-
+      Model for a review candidate with residualFileCount <= 3. Default: the
+      `review.small` model role (repo agentproto.json `models` > daemon config
+      `models` > built-in).
   reviewModelLarge:
     type: string
-    description: Model for a review candidate with residualFileCount > 3.
-    default: claude-sonnet-5
+    description: >-
+      Model for a review candidate with residualFileCount > 3, and the retry
+      reviewer. Default: the `review.large` model role (repo agentproto.json
+      `models` > daemon config `models` > built-in).
   maxReviews:
     type: number
     description: >-
@@ -47,6 +51,20 @@ inputs:
       the report when set. Omit for no notification.
 outputs: {}
 steps:
+  - id: modelRoles
+    kind: tool
+    name: Resolve the reviewer model roles
+    tool: model_roles
+    inputs:
+      repoRoot: $input.repoRoot
+      workspaceSlug: $input.workspaceSlug
+      roles:
+        - review.small
+        - review.large
+      inputs:
+        review.small: $input.reviewModelSmall
+        review.large: $input.reviewModelLarge
+
   - id: worktreeGcPlan
     kind: tool
     name: Plan worktree gc
@@ -96,8 +114,8 @@ steps:
     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
+      picked per item by entry.mjs: sonnet when residualFileCount <= 3, else
+      opus (the `review.small` / `review.large` model roles). 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

package/repo-maintenance/.agentproto/workflows/maintain/entry.mjs

@@ -4,7 +4,7 @@
 // only checks the top-level id/kind sequence, never nested step bodies).
 //
 // This has to be entry-based for ONE reason: the `review` map step's
-// per-candidate `model` selector picks haiku vs sonnet from `item
+// per-candidate `model` selector picks the small vs large reviewer model from `item
 // .residualFileCount` at RUN time. `@agentproto/workflow`'s `defineWorkflow`
 // (the pure-.md / TS-authored path) hard-rejects a non-string `model` on a
 // `kind:"agent"` step — "a run-time selector is only available on the
@@ -19,8 +19,22 @@
 import { tmpdir } from "node:os"
 import { join } from "node:path"
 
-const DEFAULT_REVIEW_MODEL_SMALL = "claude-haiku-4-5-20251001"
-const DEFAULT_REVIEW_MODEL_LARGE = "claude-sonnet-5"
+// The reviewer models are model ROLES, not ids here: the `modelRoles` step
+// (the daemon's `model_roles` tool) resolves `review.small` / `review.large`
+// at run time — explicit input > repo agentproto.json `models` > daemon
+// config `models` > built-in default. The one precedence + default table is
+// packages/runtime/src/model-roles.ts; nothing below hard-codes a model id.
+const ROLE_REVIEW_SMALL = "review.small"
+const ROLE_REVIEW_LARGE = "review.large"
+
+/** The model for `role`: the run's explicit input (kept ahead of the tool as a
+ *  belt-and-braces — the tool folds the same input in as its top layer) or
+ *  the `modelRoles` step's resolution. Undefined leaves the agent's own
+ *  AGENT.md `model` in charge. */
+export function reviewModel(b, role) {
+  const explicit = role === ROLE_REVIEW_SMALL ? b.input?.reviewModelSmall : b.input?.reviewModelLarge
+  return explicit || b.steps?.modelRoles?.models?.[role] || undefined
+}
 /** Reviews per run — 500+ candidates in one run is hours of agent turns;
  *  daily runs walk the backlog instead (a reviewed tip is skipped next time). */
 const DEFAULT_MAX_REVIEWS = 40
@@ -451,8 +465,8 @@ export default {
     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.", default: false },
-    reviewModelSmall: { type: "string", description: `Model for a review candidate with residualFileCount <= 3. Default ${DEFAULT_REVIEW_MODEL_SMALL}.`, default: DEFAULT_REVIEW_MODEL_SMALL },
-    reviewModelLarge: { type: "string", description: `Model for a review candidate with residualFileCount > 3. Default ${DEFAULT_REVIEW_MODEL_LARGE}.`, default: DEFAULT_REVIEW_MODEL_LARGE },
+    reviewModelSmall: { type: "string", description: `Model for a review candidate with residualFileCount <= 3. Default: the \`${ROLE_REVIEW_SMALL}\` model role (repo agentproto.json \`models\` > daemon config \`models\` > built-in).` },
+    reviewModelLarge: { type: "string", description: `Model for a review candidate with residualFileCount > 3, and the retry reviewer. Default: the \`${ROLE_REVIEW_LARGE}\` model role (repo agentproto.json \`models\` > daemon config \`models\` > built-in).` },
     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 ${DEFAULT_MAX_REVIEWS}.`, default: DEFAULT_MAX_REVIEWS },
     notify: {
       type: "object",
@@ -461,6 +475,20 @@ export default {
   },
   outputs: {},
   steps: [
+    {
+      id: "modelRoles",
+      kind: "tool",
+      tool: "model_roles",
+      inputs: {
+        repoRoot: "$input.repoRoot",
+        workspaceSlug: "$input.workspaceSlug",
+        roles: [ROLE_REVIEW_SMALL, ROLE_REVIEW_LARGE],
+        inputs: {
+          [ROLE_REVIEW_SMALL]: "$input.reviewModelSmall",
+          [ROLE_REVIEW_LARGE]: "$input.reviewModelLarge",
+        },
+      },
+    },
     {
       id: "worktreeGcPlan",
       kind: "tool",
@@ -505,9 +533,7 @@ export default {
           agent: { ref: REVIEWER_REF },
           cwd: REVIEWER_CWD,
           prompt: REVIEW_PROMPT,
-          model: b => ((b.item?.residualFileCount ?? 0) <= 3
-            ? (b.input?.reviewModelSmall || DEFAULT_REVIEW_MODEL_SMALL)
-            : (b.input?.reviewModelLarge || DEFAULT_REVIEW_MODEL_LARGE)),
+          model: b => reviewModel(b, (b.item?.residualFileCount ?? 0) <= 3 ? ROLE_REVIEW_SMALL : ROLE_REVIEW_LARGE),
         },
         // A reviewer can end its turn announcing calls it never made. Check
         // the store for EVERY tip of this item (the per-tip map below); if
@@ -548,7 +574,7 @@ export default {
             REVIEW_PROMPT +
             "\n\nA previous reviewer of this branch ended its turn without recording a verdict. " +
             "Recording the verdict with branch_gc_verdict IS the deliverable — do not end your turn without it.",
-          model: b => b.input?.reviewModelLarge || DEFAULT_REVIEW_MODEL_LARGE,
+          model: b => reviewModel(b, ROLE_REVIEW_LARGE),
         },
         {
           id: "reviewSettled",

package/repo-maintenance/README.md

@@ -18,8 +18,13 @@ The `maintain` workflow, one run:
    `maxReviews` (default 40) per run, newest tip first, then the larger
    residual; the rest wait for the next run (one turn per unique tip sha,
    parallelism 4, each reviewer in its own disposable detached worktree
-   under the OS tmp dir, never the live checkout): haiku when the
-   candidate's residual is 3 files or fewer, sonnet otherwise. Three spawn
+   under the OS tmp dir, never the live checkout): sonnet when the
+   candidate's residual is 3 files or fewer, opus otherwise — by default;
+   the models are the `review.small` / `review.large` **model roles** (an
+   explicit `reviewModelSmall`/`reviewModelLarge` input wins, then the repo's
+   `agentproto.json` `models`, then the daemon config `models`, then the
+   built-in default — see `@agentproto/runtime`'s `model-roles.ts`; inspect
+   with the `model_roles` tool, change with `config_set models.review.small`). Three spawn
    failures in a row stop the fan-out (the engine's circuit breaker) and
    the report lists every distinct failure reason. Each turn records a verdict via `branch_gc_verdict` —
    recording a verdict never deletes anything. A turn that ends without a

package/repo-maintenance/routines/repo-maintenance-daily/ROUTINE.md

@@ -44,8 +44,8 @@ with `applyMerged: false`. Every run:
 
 1. Plans `worktree_gc` and `branch_gc` (dry run — nothing is touched).
 2. Fans the `@agentproto/repo-maintenance-reviewer` agent out over every
-   unmerged branch candidate (haiku when its residual is 3 files or fewer,
-   sonnet otherwise), one turn per unique tip sha. Each turn records a
+   unmerged branch candidate (sonnet when its residual is 3 files or fewer,
+   opus otherwise), one turn per unique tip sha. Each turn records a
    verdict via `branch_gc_verdict` — recording never deletes anything.
 3. Re-plans to confirm every candidate got a verdict, and reports the gaps.
 4. Reports a markdown summary, and notifies (when `notify` is configured)

package/session-steward/.agentproto/APP.md

@@ -0,0 +1,20 @@
+---
+schema: app/v1
+id: '@agentproto/session-steward'
+name: Session Steward
+version: 0.1.0
+description: >-
+  Wraps up idle agent sessions: classifies them with session_wrapup_plan,
+  closes the rule-certain ones, has a cheap one-shot judge decide the
+  ambiguous ones from compact evidence, and closes or flags confident
+  verdicts with a recorded outcome. Dry run by default.
+agents:
+  - id: '@agentproto/session-steward-judge'
+    path: .agentproto/agents/session-steward-judge/AGENT.md
+workflows:
+  - id: session-steward
+    path: .agentproto/workflows/session-steward/WORKFLOW.md
+---
+
+Wraps up idle agent sessions — see README.md for how to install and run it,
+and `routines/` for the hourly scheduled template (ships disabled).

package/session-steward/.agentproto/agents/session-steward-judge/AGENT.md

@@ -0,0 +1,43 @@
+---
+schema: agent/v1
+id: '@agentproto/session-steward-judge'
+description: >-
+  Decides, from a compact evidence object in its prompt, whether ONE idle
+  agent session is done, abandoned, blocked, needs input, or still active.
+  One turn, one strict JSON verdict, then the session is released. Spawned
+  by the `session-steward` workflow's `judge` map step.
+model: role:judge.session
+boundaries:
+  - Answer from the evidence in the prompt alone — never call a tool, never read or write files
+  - Reply with exactly one JSON object and nothing else
+  - When unsure, answer `active` with a low confidence
+tools:
+  - session_evidence
+workflows:
+  - ref: session-steward
+---
+
+You are the session steward's judge. Each prompt carries the evidence for ONE
+idle AI coding-agent session: its label, cwd, idle time, RAM, the planner's
+signals (last assistant message, pending tool call, parent ended, worktree
+merged), its last few turns, and — for a worktree session — branch, dirty
+counts, ahead/behind and PR state.
+
+Decide one verdict:
+
+- `done` — the task visibly finished: a PR was opened or merged, a final
+  report was given, or the user said thanks/ok with nothing pending.
+- `abandoned` — superseded or a dead end, with nothing worth keeping.
+- `blocked` — waiting on something external (CI, another session, a
+  dependency).
+- `needs-input` — waiting on a human answer or decision.
+- `active` — mid-work; keep it.
+
+Closing a session that still had work is worse than leaving an idle one open:
+when unsure, answer `active` with a low confidence.
+
+Reply with ONLY the JSON object the prompt asks for — `sessionId`, `verdict`,
+`confidence` (0..1), `reason` (one line). No prose, no code fence.
+
+The one tool on your gateway (`session_evidence`) is there only because an
+agent that declares no tools gets the full daemon gateway; you do not need it.

package/session-steward/.agentproto/workflows/session-steward/WORKFLOW.md

@@ -0,0 +1,277 @@
+---
+name: Session Steward
+id: session-steward
+description: >-
+  Plan idle-session wrap-up (session_wrapup_plan), close the rule-certain
+  `close`/`stuck` sessions, judge the ambiguous `judge` ones with a cheap
+  one-shot model over compact evidence, optionally ask a session directly,
+  then close or flag the confident verdicts with a recorded outcome — and
+  report. Dry run unless `apply` is true. Entry-based (see entry.mjs): every
+  decision between the tool calls is a real function (candidate split,
+  strict verdict parse, confidence threshold, report).
+version: 0.1.0
+entry: ./entry.mjs
+inputs:
+  idleMinutes:
+    type: number
+    description: Idle threshold in minutes.
+    default: 30
+  apply:
+    type: boolean
+    description: Close/flag sessions. False = dry run (plan + verdicts, no mutation).
+    default: false
+  minConfidence:
+    type: number
+    description: Judge confidence needed to act on a verdict.
+    default: 0.8
+  judge:
+    type: string
+    description: >-
+      Judge backend — `auto` (Jev when JEV_API_KEY resolves, else the agent
+      judge), `jev`, or `agent`. A Jev failure always falls back to the agent
+      judge for that session.
+    default: auto
+  jevModel:
+    type: string
+    description: Jev model.
+    default: jev-latest
+  judgeModel:
+    type: string
+    description: >-
+      Model for the agent judge. Default: the `judge.session` model role
+      (repo agentproto.json `models` > daemon config `models` > built-in).
+  maxJudged:
+    type: number
+    description: Most `judge` sessions judged per run, most RAM first.
+    default: 15
+  askSessions:
+    type: boolean
+    description: >-
+      Ask low-confidence idle sessions directly whether they're done. Off by
+      default — it spends a turn in someone else's conversation.
+    default: false
+  callerSessionId:
+    type: string
+    description: The calling session's id — never a candidate.
+outputs: {}
+steps:
+  - id: modelRoles
+    kind: tool
+    name: Resolve the judge model role
+    tool: model_roles
+    inputs:
+      roles:
+        - judge.session
+      inputs:
+        judge.session: $input.judgeModel
+  - id: settings
+    kind: transform
+    name: Resolve inputs with their defaults
+    description: Entry-based — see entry.mjs's resolveSettings.
+
+  - id: plan
+    kind: tool
+    name: Classify idle sessions (dry run)
+    tool: session_wrapup_plan
+    inputs:
+      idleMinutes: $steps.settings.idleMinutes
+
+  - id: candidates
+    kind: transform
+    name: Split close / stuck / judge, drop keep and the caller
+    description: >-
+      Entry-based — splitCandidates. `judge` is ordered most RAM first and
+      capped at `maxJudged`.
+
+  - id: ruleApplyQueue
+    kind: transform
+    name: Rule verdicts to apply
+    description: >-
+      Entry-based. Empty unless `apply`: `close` → done, `stuck` → abandoned.
+
+  - id: autoApply
+    kind: map
+    name: Close rule-certain sessions
+    over: $steps.ruleApplyQueue
+    parallelism: 1
+    onError: collect
+    steps:
+      - id: autoApplyOne
+        kind: tool
+        tool: session_wrapup_apply
+        inputs:
+          sessionIds: [$item.sessionId]
+          verdict: $item.verdict
+          note: $item.note
+
+  - id: evidence
+    kind: map
+    name: Collect compact evidence per judge candidate
+    over: $steps.candidates.judge
+    parallelism: 4
+    onError: collect
+    steps:
+      - id: evidenceOne
+        kind: tool
+        tool: session_evidence
+        inputs:
+          sessionId: $item.sessionId
+
+  - id: judgeQueue
+    kind: transform
+    name: Candidates with evidence
+    description: Entry-based.
+
+  - id: jevQueue
+    kind: transform
+    name: Candidates for the Jev backend
+    description: Entry-based. Empty when `judge` is `agent`.
+
+  - id: jevJudge
+    kind: map
+    name: Jev judge per candidate
+    description: >-
+      One `session_judge_jev` call per candidate — a calibrated `choice` over
+      the five verdicts with probabilities, state = the evidence. A missing
+      key or any failure is `ok:false`, never an error, and that candidate
+      goes to the agent judge.
+    over: $steps.jevQueue
+    parallelism: 4
+    onError: collect
+    steps:
+      - id: jevOne
+        kind: tool
+        tool: session_judge_jev
+        inputs:
+          sessionId: $item.entry.sessionId
+          evidence: $item.evidence
+          model: $steps.settings.jevModel
+
+  - id: agentJudgeQueue
+    kind: transform
+    name: Candidates Jev didn't answer
+    description: Entry-based — buildAgentJudgeQueue.
+
+  - id: judge
+    kind: map
+    name: One-shot agent judge per remaining candidate
+    description: >-
+      One turn of `@agentproto/session-steward-judge` on `judgeModel`, evidence
+      in the prompt, strict JSON verdict out. A malformed reply is `active`
+      with confidence 0. The judge session is released (killed + archived)
+      when its item settles.
+    over: $steps.agentJudgeQueue
+    parallelism: 3
+    onError: collect
+    steps:
+      - id: judgeOne
+        kind: agent
+        agent:
+          ref: "@agentproto/session-steward-judge"
+        prompt: $item.judgePrompt
+
+  - id: verdicts
+    kind: transform
+    name: One verdict row per judged candidate
+    description: Entry-based — collectVerdicts.
+
+  - id: askQueue
+    kind: transform
+    name: Low-confidence idle sessions to ask directly
+    description: Entry-based. Empty unless `askSessions`.
+
+  - id: ask
+    kind: map
+    name: Ask the session itself (opt-in)
+    description: >-
+      One `agent_prompt` (queue:false), a bounded ~3 min `session_monitor`
+      wait, then its newest assistant turn is parsed for `STEWARD: DONE` /
+      `STEWARD: NOT-DONE`. See entry.mjs.
+    over: $steps.askQueue
+    parallelism: 2
+    onError: collect
+    steps:
+      - id: askPrompt
+        kind: tool
+        tool: agent_prompt
+        inputs:
+          sessionId: $item.sessionId
+
+  - id: finalVerdicts
+    kind: transform
+    name: Merge declared answers over judge verdicts
+    description: Entry-based — mergeDeclared.
+
+  - id: judgedApplyQueue
+    kind: transform
+    name: Confident verdicts to apply
+    description: >-
+      Entry-based. Empty unless `apply`: done/abandoned/blocked/needs-input at
+      or above `minConfidence`.
+
+  - id: judgedApply
+    kind: map
+    name: Close or flag judged sessions
+    over: $steps.judgedApplyQueue
+    parallelism: 1
+    onError: collect
+    steps:
+      - id: judgedApplyOne
+        kind: tool
+        tool: session_wrapup_apply
+        inputs:
+          sessionIds: [$item.sessionId]
+          verdict: $item.verdict
+          judgedBy: $item.judgedBy
+          note: $item.note
+
+  - id: report
+    kind: transform
+    name: Build the markdown report
+    description: Entry-based — buildReport.
+
+result:
+  report: $steps.report
+  apply: $steps.settings.apply
+  candidates: $steps.candidates
+  verdicts: $steps.finalVerdicts
+  autoApply: $steps.autoApply
+  judgedApply: $steps.judgedApply
+---
+
+# Session Steward — `session-steward` workflow
+
+`session_wrapup_plan` → rules pass over `close`/`stuck` → compact evidence per
+`judge` session → one cheap judge turn each → (opt-in) ask the session itself →
+close or flag confident verdicts through `session_wrapup_apply` → markdown
+report with RAM freed / still held.
+
+## Safety
+
+- `apply: false` (the default) mutates nothing: every mutating map runs over
+  an empty list.
+- `session_wrapup_apply` re-classifies each id right before acting and always
+  refuses `keep`-class ids; this workflow never feeds it one.
+- Rules only ever close `close`/`stuck` ids; a `keepAlive` session is never
+  in those classes, so only a confident judge verdict (with `judgedBy`) can
+  close it — as FIX-9A allows.
+- A malformed judge reply is `active` with confidence 0 — never acted on.
+- The caller's own session (`callerSessionId`) is dropped from every list.
+- `blocked` / `needs-input` only FLAG a session; it keeps running.
+
+## The judge
+
+Two backends. **Jev** (TypeSafe System One, `session_judge_jev`) is the
+default whenever `JEV_API_KEY` resolves (daemon env, else the host secret
+resolver): one calibrated `choice` over the five verdicts; confidence is the
+chosen verdict's probability, the full probabilities go in the report, and
+`judgedBy` is `jev:<model>`. Any Jev failure (no key under `judge: jev`, a
+non-2xx after retries, a malformed answer) falls back to the agent judge for
+that session and the report says so — a Jev error never closes anything.
+
+The **agent judge**:
+
+`@agentproto/session-steward-judge` answers from the evidence in its prompt
+and is told not to call tools. Its gateway mount is scoped to the one
+read-only `session_evidence` tool: declaring no `tools:` at all would mount
+the FULL daemon gateway for a claude-code judge (the host's default).