@agentproto/apps 0.21.0 → 0.21.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentproto/apps",
-  "version": "0.21.0",
+  "version": "0.21.1",
   "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",
@@ -173,9 +173,9 @@
   },
   "dependencies": {
     "zod": "^4.6.5",
-    "@agentproto/agent": "0.2.5",
     "@agentproto/app-client": "0.4.1",
-    "@agentproto/app-kit": "1.7.0",
+    "@agentproto/app-kit": "1.7.1",
+    "@agentproto/agent": "0.2.5",
     "@agentproto/workflow": "0.7.1"
   },
   "peerDependencies": {

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

@@ -168,13 +168,21 @@ export function reviewableWorktrees(worktreeGcPlanResult) {
   const entries = Array.isArray(worktreeGcPlanResult?.plan) ? worktreeGcPlanResult.plan : []
   for (const w of entries) {
     if (w?.class !== "hold" || !w.branch || !w.path) continue
-    if (w.liveness?.state !== "idle" || w.tree?.state !== "clean") continue
+    if (w.liveness?.state !== "idle" || treeState(w.tree) !== "clean") continue
     if (w.integration?.state === "open") continue
     out.set(w.path, w.branch)
   }
   return out
 }
 
+/** A worktree_gc plan entry's tree state. The daemon's `worktree_gc` tool
+ *  flattens it to the bare discriminant (`tree: "clean"`, `toGcPlanEntryView`
+ *  in packages/cli/src/commands/worktree.ts); the engine's own `GcPlanEntry`
+ *  (and `agentproto worktree gc --json`) carries `{ state, … }`. */
+function treeState(tree) {
+  return typeof tree === "string" ? tree : tree?.state
+}
+
 /** The worktree path a branch_gc entry is held by, when that hold is the only
  *  thing between it and `review`: held for `worktree`, unmerged, old enough,
  *  and the worktree is one {@link reviewableWorktrees} kept. Else null. */

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

@@ -56,6 +56,24 @@ inputs:
       Ask low-confidence idle sessions directly whether they're done. Off by
       default — it spends a turn in someone else's conversation.
     default: false
+  recurring:
+    type: boolean
+    description: >-
+      Set by scheduled runs (the hourly routine). A recurring run closes
+      sessions nobody asked about, so a keepAlive session must also have been
+      idle `keepAliveAskAfterMinutes`. Default false = an on-demand run, which
+      applies no such delay.
+    default: false
+  keepAliveAskAfterMinutes:
+    type: number
+    description: >-
+      With `askSessions`, for `recurring` runs only: a keepAlive session whose
+      worktree is merged or clean (nothing uncommitted, nothing ahead of base)
+      is asked only once idle this many minutes; 0 disables the recurring
+      keepAlive ask. On-demand runs ignore it. keepAlive only re-lights a
+      session after a daemon restart; it does not stop a declared DONE from
+      closing it.
+    default: 1440
   callerSessionId:
     type: string
     description: The calling session's id — never a candidate.
@@ -342,7 +360,10 @@ steps:
   - id: askQueue
     kind: transform
     name: Low-confidence idle sessions to ask directly
-    description: Entry-based. Empty unless `askSessions`.
+    description: >-
+      Entry-based. Empty unless `askSessions`. A keepAlive session is included
+      only with a merged/clean worktree, and on a `recurring` run only once
+      idle `keepAliveAskAfterMinutes` (default 1440, 0 = never).
 
   - id: ask
     kind: map
@@ -488,8 +509,16 @@ as observed, never nudged.
 - `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.
+  in those classes, so only a confident judge verdict or a declared DONE (with
+  `judgedBy`) can close it — as FIX-9A allows. `keepAlive` means "re-light
+  after a daemon restart", not "never close": with `askSessions`, a keepAlive
+  session whose worktree is merged or clean (no uncommitted change, nothing
+  ahead of base; unknown worktree is not clean) is asked like any other. Closing
+  is an active act, so an on-demand run (`recurring: false`, e.g. `agentproto
+  steward --ask-sessions`) applies no idle delay to it beyond `idleMinutes`; only
+  a `recurring` run waits `keepAliveAskAfterMinutes` (default 1440 = 24 h, 0
+  disables), so nobody wakes up to find a session closed that they meant to
+  resume. A steward close is a deliberate end, so the sentinel never revives it.
 - 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.

package/session-steward/.agentproto/workflows/session-steward/entry.mjs

@@ -57,6 +57,11 @@ import {
 
 const DEFAULT_IDLE_MINUTES = 30
 const DEFAULT_MIN_CONFIDENCE = 0.8
+/** Recurring (scheduled) runs only: a keepAlive session must have been idle
+ *  this long before it may be asked, so a session its owner meant to pick up
+ *  tomorrow is not closed overnight. 0 turns the recurring keepAlive ask off.
+ *  An on-demand run (`recurring: false`) has no such delay. */
+const DEFAULT_KEEPALIVE_ASK_AFTER_MINUTES = 1440
 /** Terminal sessions older than this (hours since they ended) are not listed
  *  as relabel candidates. */
 const DEFAULT_RELABEL_WINDOW_HOURS = 24
@@ -118,6 +123,8 @@ export function resolveSettings(input, modelRoles) {
     jevModel: typeof i.jevModel === "string" && i.jevModel.trim() ? i.jevModel.trim() : DEFAULT_JEV_MODEL,
     maxJudged: Math.floor(num(i.maxJudged, DEFAULT_MAX_JUDGED)),
     askSessions: i.askSessions === true,
+    recurring: i.recurring === true,
+    keepAliveAskAfterMinutes: num(i.keepAliveAskAfterMinutes, DEFAULT_KEEPALIVE_ASK_AFTER_MINUTES, { min: 0 }),
     callerSessionId: typeof i.callerSessionId === "string" && i.callerSessionId ? i.callerSessionId : null,
     callerOrigin: typeof i.callerOrigin === "string" && i.callerOrigin ? i.callerOrigin : null,
     appId: typeof i.appId === "string" ? i.appId.trim() : DEFAULT_APP_ID,
@@ -427,8 +434,33 @@ export function collectVerdicts(evidenceResult, judgeQueue, jevResult, jevQueue,
 
 // ── ask (opt-in) ─────────────────────────────────────────────────────────
 
-/** Sessions to ask directly: judged below `minConfidence`, and idle, not
- *  keepAlive, not awaitingInput — only when `askSessions`. */
+/** Nothing to lose in the session's worktree: it is merged (the plan's signal
+ *  or the PR state), or it is a linked worktree with no uncommitted changes
+ *  and no commits beyond the base. No worktree info at all is unknown, not
+ *  clean — a session in a plain checkout stays out. */
+export function worktreeHasNothingToLose(evidence) {
+  if (evidence?.signals?.worktreeMerged === true) return true
+  const wt = evidence?.worktree
+  if (!wt) return false
+  if (wt.pr?.state === "merged") return true
+  return wt.dirty === false && wt.ahead === 0
+}
+
+/** keepAlive is the restart-relight flag; closing is a separate, active
+ *  decision. A keepAlive session whose worktree holds nothing to lose may be
+ *  asked. An on-demand run (a human asked for it) applies no idle delay beyond
+ *  the plan's own `idleMinutes`. A `recurring` run closes things nobody asked
+ *  about, so it also waits `keepAliveAskAfterMinutes` of idleness (0 = never). */
+export function keepAliveAskEligible(evidence, settings) {
+  if (evidence?.keepAlive !== true || !worktreeHasNothingToLose(evidence)) return false
+  if (settings.recurring !== true) return true
+  const after = settings.keepAliveAskAfterMinutes
+  return after > 0 && typeof evidence.idleMinutes === "number" && evidence.idleMinutes >= after
+}
+
+/** Sessions to ask directly: judged below `minConfidence`, not awaitingInput
+ *  or busy, and either not keepAlive or a keepAlive passing
+ *  {@link keepAliveAskEligible} — only when `askSessions`. */
 export function buildAskQueue(verdicts, settings) {
   if (!settings?.askSessions) return []
   return (verdicts ?? [])
@@ -436,7 +468,7 @@ export function buildAskQueue(verdicts, settings) {
       r =>
         r.evidence &&
         r.confidence < settings.minConfidence &&
-        r.evidence.keepAlive !== true &&
+        (r.evidence.keepAlive !== true || keepAliveAskEligible(r.evidence, settings)) &&
         r.evidence.awaitingInput !== true &&
         r.evidence.busy !== true,
     )
@@ -995,6 +1027,8 @@ export default {
     judgeModel: { type: "string", description: `Model for the agent judge. Default: the \`${ROLE_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 ${DEFAULT_MAX_JUDGED}.`, default: DEFAULT_MAX_JUDGED },
     askSessions: { type: "boolean", description: "Ask low-confidence idle sessions directly whether they're done. Default false — it spends a turn in someone else's conversation.", default: false },
+    recurring: { type: "boolean", description: "Set by scheduled runs (the hourly routine). A recurring run closes sessions nobody asked about, so a keepAlive session must also have been idle `keepAliveAskAfterMinutes`. Default false = an on-demand run, which applies no such delay.", default: false },
+    keepAliveAskAfterMinutes: { type: "number", description: `With \`askSessions\`, for \`recurring\` runs only: a keepAlive session whose worktree is merged or clean (nothing uncommitted, nothing ahead of base) is asked only once idle this many minutes; 0 disables the recurring keepAlive ask. On-demand runs ignore it. keepAlive only re-lights a session after a daemon restart; it does not stop a declared DONE from closing it. Default ${DEFAULT_KEEPALIVE_ASK_AFTER_MINUTES}.`, default: DEFAULT_KEEPALIVE_ASK_AFTER_MINUTES },
     callerSessionId: { type: "string", description: "The calling session's id — never a candidate. The CLI passes AGENTPROTO_SESSION_ID." },
     callerOrigin: { type: "string", description: "The calling session's origin (`cron:<jobId>`) — an older run of the SAME cron job is never judged as user work." },
     appId: { type: "string", description: `Installed app whose \`app_state\` ledger holds the verdict memory. Default ${DEFAULT_APP_ID}.` },

package/session-steward/README.md

@@ -33,10 +33,18 @@ loader path can carry.
      judge session is released (killed + archived) when its item settles.
    Verdicts: `done|abandoned|blocked|needs-input|active`. A judge error never
    closes anything.
-5. `ask` (only with `askSessions`) — low-confidence, idle, non-keepAlive,
-   not-awaiting-input sessions get ONE prompt asking them to reply
+5. `ask` (only with `askSessions`) — low-confidence, idle, not-awaiting-input
+   sessions get ONE prompt asking them to reply
    `STEWARD: DONE …` / `STEWARD: NOT-DONE …`; a ~3 min bounded wait; the
-   answer becomes a `declared` verdict.
+   answer becomes a `declared` verdict. `keepAlive` only re-lights a session
+   after a daemon restart, so it does not exempt one from the ask: a keepAlive
+   session whose worktree is merged or clean (nothing uncommitted, nothing
+   ahead of base; no worktree info counts as not clean) is asked too. Closing
+   is an active act: an on-demand run (`agentproto steward --ask-sessions`)
+   adds no idle delay beyond `--idle`. Only a scheduled run (`recurring: true`,
+   as the hourly routine sets) waits `keepAliveAskAfterMinutes` (default 1440,
+   24 h; 0 turns it off), so a session you meant to resume is not closed
+   overnight.
 6. `judgedApply` (only with `apply`) — confident `done`/`abandoned` close
    (resumable, with a recorded outcome); confident `blocked`/`needs-input`
    only flag. Everything else is left alone and reported.

package/session-steward/routines/session-steward-hourly/ROUTINE.md

@@ -21,6 +21,9 @@ target:
   inputs:
     apply: true
     askSessions: false
+    # Scheduled run: if askSessions is ever turned on here, a keepAlive session
+    # is asked only after keepAliveAskAfterMinutes idle (default 1440, 0 = never).
+    recurring: true
     # Origin policy (the committed default): never close a human's session.
     # `chat-starter`/`vscode` (and any root with no origin and no parent) are
     # FLAG-ONLY; `cron:*` jobs, `gate`, `workflow` and `review` sessions, and executors (a session with