@agentproto/apps 0.15.0 → 0.17.0

package/session-steward/README.md

@@ -0,0 +1,70 @@
+# Session Steward
+
+A built-in agentproto app that wraps up idle agent sessions. It sits on top
+of the runtime's `session_wrapup_plan` / `session_wrapup_apply` tools
+(FIX-9A) and adds the missing loop: a cheap judge for the ambiguous
+sessions. Hand-authored bundle (`.agentproto/APP.md` + `agents/` +
+`workflows/`), like `repo-maintenance` — the workflow's decisions (candidate
+split, strict verdict parse, confidence threshold, report) are real
+functions in `workflows/session-steward/entry.mjs`, which only the `entry:`
+loader path can carry.
+
+## What one run does
+
+1. `plan` — `session_wrapup_plan { idleMinutes }` (dry run).
+2. `autoApply` (only with `apply`) — `close` ids →
+   `session_wrapup_apply { verdict: "done", note: "steward-rules: …" }`,
+   `stuck` ids → `{ verdict: "abandoned" }`.
+3. `evidence` — per `judge` candidate (at most `maxJudged`, most RAM first),
+   the read-only `session_evidence` tool: label, cwd, idle, keepAlive, RAM,
+   the plan's signals, the last ~10 turns (~3 KB), and worktree
+   branch/dirty/ahead/behind/PR. Under ~5 KB per session.
+4. `judge` — per candidate, backend picked by `judge` (default `auto`):
+   - **Jev** (`auto` when `JEV_API_KEY` resolves — daemon env, else the host
+     secret resolver — or `judge: "jev"`): one `session_judge_jev` call, a
+     calibrated `choice` over the five verdicts with the evidence as state;
+     confidence = the chosen verdict's probability, full probabilities in the
+     report, `judgedBy: jev:<jevModel>`.
+   - **Agent** (`judge: "agent"`, `auto` without a key, or any Jev failure
+     for that session — reported as such): one turn of
+     `@agentproto/session-steward-judge` on `judgeModel` (default: the `judge.session` model role — explicit input > repo `agentproto.json` `models` > daemon config `models` > built-in sonnet; see `model_roles`),
+     strict JSON verdict. A malformed reply is `active`, confidence 0. The
+     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
+   `STEWARD: DONE …` / `STEWARD: NOT-DONE …`; a ~3 min bounded wait; the
+   answer becomes a `declared` verdict.
+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.
+7. `report` — markdown table (class, session, idle, RAM, verdict,
+   confidence, reason, action) plus RAM freed / still held.
+
+## Running it
+
+```bash
+agentproto steward --wait                     # dry run: plan + verdicts, report
+agentproto steward --apply --wait             # close / flag confident verdicts
+agentproto steward --apply --idle 60 --min-confidence 0.9 --judge agent
+agentproto steward --ask-sessions --wait      # also ask low-confidence sessions
+```
+
+`agentproto steward` installs (upserts) this app and starts the workflow via
+`workflow_run_file`; it passes `AGENTPROTO_SESSION_ID` as `callerSessionId`
+so a run never judges the session that started it. Or call the daemon
+directly:
+
+```bash
+agentproto app install packages/apps/session-steward
+agentproto workflow run-file \
+  packages/apps/session-steward/.agentproto/workflows/session-steward/WORKFLOW.md \
+  --input-json '{"apply": false}'
+```
+
+## Routine
+
+`routines/session-steward-hourly` is an AIP-41 `ROUTINE.md` template: hourly,
+`apply: true`, `askSessions: false`, shipped `enabled: false` — nothing
+starts closing sessions on install. Its own doc lists the enabling steps.

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

@@ -0,0 +1,68 @@
+---
+schema: routine/v1
+id: session-steward-hourly
+description: |
+  Hourly APPLY pass of the `session-steward` workflow — `apply: true`,
+  `askSessions: false`: closes rule-certain idle sessions (`close`/`stuck`),
+  judges the ambiguous ones (Jev when JEV_API_KEY resolves, else the one-shot
+  agent judge), and closes or flags confident verdicts with a recorded,
+  resumable outcome. Never asks a session anything. Ships DISABLED
+  (`enabled: false`) — nothing starts closing sessions on install; install it
+  into a workspace's `.routines/` and flip `enabled: true` to activate.
+version: "1.0.0"
+schedule:
+  kind: cron
+  cron: "0 * * * *"
+  timezone: "UTC"
+  catchup: skip
+target:
+  workflow:
+    file: <absolute-path-to-agentproto-ts>/packages/apps/session-steward/.agentproto/workflows/session-steward/WORKFLOW.md
+  inputs:
+    apply: true
+    askSessions: false
+retry:
+  max_attempts: 1
+  backoff: fixed
+on_failure:
+  create_work_item: true
+  fire_event: session-steward.hourly.failed
+fires_events:
+  - session-steward.hourly.completed
+  - session-steward.hourly.failed
+enabled: false
+tags: [session-steward, sessions, maintenance]
+---
+
+# Session steward — hourly apply
+
+Runs every hour on the hour (UTC), firing the `session-steward` workflow
+(`../../.agentproto/workflows/session-steward/WORKFLOW.md`) with
+`apply: true` and `askSessions: false`. Every run:
+
+1. Plans with `session_wrapup_plan` (idle ≥ 30 min by default).
+2. Closes `close`-class sessions as `done` and `stuck`-class ones as
+   `abandoned` — resumable, with a recorded outcome.
+3. Judges up to 15 `judge`-class sessions, most RAM first, and closes
+   (`done`/`abandoned`) or flags (`blocked`/`needs-input`) only verdicts at
+   confidence ≥ 0.8. Everything else is left alone and reported.
+
+`keep`-class sessions, the caller's own session, and anything busy or
+awaiting input are never touched (`session_wrapup_apply` re-checks every id
+right before acting).
+
+## Enabling
+
+1. Run it by hand first and read the reports:
+   `agentproto steward --wait` (dry run), then `agentproto steward --apply --wait`.
+2. Copy this directory to `<workspace>/.routines/session-steward-hourly/`.
+3. Set `enabled: true` and point `target.workflow.file` at wherever
+   `session-steward/WORKFLOW.md` lives in that environment.
+4. Optional: set `JEV_API_KEY` in the daemon's environment to judge with Jev.
+5. Reload routines, or fire it once via `routine_trigger`.
+
+## Failure routing
+
+One attempt, then `on_failure` opens a work item and fires
+`session-steward.hourly.failed`. A clean run fires
+`session-steward.hourly.completed`.