@agentproto/apps 0.18.0 → 0.20.0

package/session-steward/.agentproto/workflows/session-steward/origin-policy.mjs

@@ -0,0 +1,115 @@
+// Pure origin policy for the session steward: whether a candidate session may
+// be CLOSED or only FLAGGED is a function of its provenance, so it is a real
+// function here — no I/O, no clock, no daemon state. Imported by entry.mjs
+// (the WORKFLOW.md step graph) and pinned by unit tests. The workflow inputs
+// `userOrigins` / `closableOrigins` configure it; the defaults below are the
+// committed policy: a human is in the loop, so a human-launched session is
+// never closed autonomously.
+
+/** Origins the steward must NEVER close — a human launched the session, so a
+ *  close is always downgraded to a flag. Exact match, or a trailing `*`. */
+export const DEFAULT_USER_ORIGINS = ["chat-starter", "vscode"]
+/** Origins the steward MAY close under the current rules. `cron:*` matches
+ *  every cron-spawned job (`origin: "cron:<jobId>"`); `gate` matches
+ *  supervision-gate sessions. */
+export const DEFAULT_CLOSABLE_ORIGINS = ["cron:*", "gate"]
+
+/** The reason shown (and recorded) when a would-be close is bounded by origin. */
+export const USER_ORIGIN_REASON = "flag (origine utilisateur)"
+
+const isNonEmptyString = (v) => typeof v === "string" && v.trim().length > 0
+
+/** One origin-list entry vs a session's origin. A trailing `*` is a prefix
+ *  wildcard (`cron:*` matches `cron:kill-idle-sessions`); otherwise exact. */
+export function matchesOrigin(origin, pattern) {
+  if (!isNonEmptyString(origin) || !isNonEmptyString(pattern)) return false
+  const p = pattern.trim()
+  if (p.endsWith("*")) return origin.startsWith(p.slice(0, -1))
+  return origin === p
+}
+
+/** Fold raw (possibly absent/empty/malformed) input lists into a usable
+ *  policy. An empty list falls back to its default — the conservative
+ *  direction: a session still has to clear an origin bound to be closed. */
+export function resolveOriginPolicy(policy) {
+  const p = policy ?? {}
+  const list = (value, fallback) => {
+    const kept = Array.isArray(value) ? value.filter(isNonEmptyString).map((s) => s.trim()) : []
+    return kept.length > 0 ? kept : fallback
+  }
+  return {
+    userOrigins: list(p.userOrigins, DEFAULT_USER_ORIGINS),
+    closableOrigins: list(p.closableOrigins, DEFAULT_CLOSABLE_ORIGINS),
+  }
+}
+
+/** The origin class of a candidate:
+ *  - `"user"` — human-launched: a `userOrigins` match, OR a root with no
+ *    origin and no parent. FLAG ONLY, never close.
+ *  - `"closable"` — a `closableOrigins` match (cron:*, gate) or an executor
+ *    (has a `parentSessionId`). Close allowed under the current rules.
+ *  `userOrigins` wins over both `closableOrigins` and the executor rule, so a
+ *  `vscode` executor is still user-origin. An unrecognized root origin is
+ *  treated as `"user"` (conservative). */
+export function classifyOrigin(session, policy) {
+  const { userOrigins, closableOrigins } = resolveOriginPolicy(policy)
+  const origin = session?.origin
+  if (isNonEmptyString(origin) && userOrigins.some((o) => matchesOrigin(origin, o))) return "user"
+  if (isNonEmptyString(origin) && closableOrigins.some((o) => matchesOrigin(origin, o))) return "closable"
+  if (isNonEmptyString(session?.parentSessionId)) return "closable"
+  return "user"
+}
+
+const CLOSE_VERDICTS = new Set(["done", "abandoned"])
+const FLAG_VERDICTS = new Set(["blocked", "needs-input"])
+
+/**
+ * The single decision the steward acts on, pure over its arguments:
+ * `{ action: "close" | "flag" | "skip", reason }`. `reason` is the label the
+ * report shows and states the retained action even in a dry run (with a
+ * `(dry run)` marker), so `action` never depends on `apply`; the queue
+ * builders separately gate execution on `apply`.
+ *
+ *  - rule-certain `close`/`stuck` → `close`;
+ *  - a judge `done`/`abandoned` at or above `minConfidence` → `close`;
+ *  - a judge `blocked`/`needs-input` at or above `minConfidence` → `flag`;
+ *  - anything else (`active`, below threshold, unknown verdict/class) → `skip`;
+ *  - a user-origin candidate is ALWAYS downgraded to `flag` — even a
+ *    rule-certain close or a confident `done` — with {@link USER_ORIGIN_REASON}.
+ */
+export function decideAction({ session, planClass, verdict, confidence, apply, policy, minConfidence } = {}) {
+  const originClass = classifyOrigin(session, policy)
+  const dry = apply !== true
+  const skipped = (reason) => ({ action: "skip", reason: dry ? `${reason} (dry run)` : reason })
+
+  let action
+  let reason
+  if (planClass === "close") {
+    action = "close"
+    reason = "close (règle certaine)"
+  } else if (planClass === "stuck") {
+    action = "close"
+    reason = "close (stuck, jamais démarrée)"
+  } else if (planClass === "judge") {
+    if (typeof confidence === "number" && typeof minConfidence === "number" && confidence < minConfidence) {
+      return skipped(`skip (confiance ${confidence} < ${minConfidence})`)
+    }
+    if (CLOSE_VERDICTS.has(verdict)) {
+      action = "close"
+      reason = `close (verdict ${verdict} confiant)`
+    } else if (FLAG_VERDICTS.has(verdict)) {
+      action = "flag"
+      reason = `flag (${verdict})`
+    } else {
+      return skipped(`skip (verdict ${verdict ?? "inconnu"})`)
+    }
+  } else {
+    return skipped(`skip (classe ${planClass ?? "inconnue"})`)
+  }
+
+  if (originClass === "user" && action === "close") {
+    action = "flag"
+    reason = USER_ORIGIN_REASON
+  }
+  return { action, reason: dry ? `${reason} (dry run)` : reason }
+}

package/session-steward/README.md

@@ -14,7 +14,8 @@ loader path can carry.
 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" }`.
+   `stuck` ids → `{ verdict: "abandoned" }` — unless the session is
+   user-origin, which is flagged instead (see Origin policy).
 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
@@ -39,9 +40,25 @@ loader path can carry.
 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,
+7. `report` — markdown table (class, session, origin, idle, RAM, verdict,
    confidence, reason, action) plus RAM freed / still held.
 
+## Origin policy (never close a human's session)
+
+Every candidate's `origin`/`parentSessionId` runs through the pure
+`decideAction` (`workflows/session-steward/origin-policy.mjs`), configured by
+the `userOrigins` / `closableOrigins` inputs:
+
+- **Flag only, never close:** `chat-starter`, `vscode`, and any root with no
+  `origin` and no `parentSessionId` (a human launched it). A would-be close —
+  even a rule-certain `close`/`stuck`, even a confident `done` — is recorded
+  as a `needs-input` flag with reason `flag (origine utilisateur)`.
+- **Close allowed:** `cron:*`, `gate`, and executors (a session with a
+  `parentSessionId`).
+
+A trailing `*` in either list is a prefix wildcard. The report carries the
+origin column and the retained action in dry run as well as apply.
+
 ## Running it
 
 ```bash

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

@@ -21,6 +21,12 @@ target:
   inputs:
     apply: true
     askSessions: false
+    # 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` sessions, and executors (a session with
+    # a parentSessionId) stay closeable. A trailing `*` is a prefix wildcard.
+    userOrigins: ["chat-starter", "vscode"]
+    closableOrigins: ["cron:*", "gate"]
 retry:
   max_attempts: 1
   backoff: fixed
@@ -42,7 +48,9 @@ Runs every hour on the hour (UTC), firing the `session-steward` workflow
 
 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.
+   `abandoned` — resumable, with a recorded outcome — **unless the session is
+   user-origin** (`chat-starter`, `vscode`, or a root with no origin and no
+   parent), which is flagged instead.
 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.
@@ -51,6 +59,21 @@ Runs every hour on the hour (UTC), firing the `session-steward` workflow
 awaiting input are never touched (`session_wrapup_apply` re-checks every id
 right before acting).
 
+## Origin policy
+
+The steward bounds every action by the candidate's `origin` (pure
+`decideAction`, `workflows/session-steward/origin-policy.mjs`):
+
+- **Flag only, never close:** `chat-starter`, `vscode`, and any root with no
+  `origin` and no `parentSessionId` (a human launched it). A would-be close —
+  even a rule-certain `close`/`stuck`, even a confident `done` — becomes a
+  `needs-input` flag with reason `flag (origine utilisateur)`.
+- **Close allowed:** `cron:*` (any cron job), `gate`, and executors (a
+  session with a `parentSessionId`).
+
+Both lists are workflow inputs (`userOrigins`, `closableOrigins`); the values
+above are the committed default. A trailing `*` is a prefix wildcard.
+
 ## Enabling
 
 1. Run it by hand first and read the reports:

package/session-steward/scripts/sessions-snapshot.sh

@@ -0,0 +1,85 @@
+#!/usr/bin/env bash
+# Session snapshot: the 50 most recently active daemon agent sessions, written
+# to a markdown file. Data comes from the daemon — never hand-edited.
+#
+# Usage: ./scripts/sessions-snapshot.sh [out.md] [count]
+#   default out: data/sessions-latest.md, default count: 50
+
+set -euo pipefail
+here="$(cd "$(dirname "$0")" && pwd)"
+app_root="$(dirname "$here")"
+out="${1:-$app_root/data/sessions-latest.md}"
+count="${2:-50}"
+mkdir -p "$(dirname "$out")"
+
+# GET /sessions returns { sessions: [...] } with full descriptors and ignores
+# ?limit, so sorting + truncation happen here.
+tmp="$(mktemp -d)"
+trap 'rm -rf "$tmp"' EXIT
+curl -sf http://127.0.0.1:18790/sessions -o "$tmp/sessions.json"
+curl -sf "http://127.0.0.1:18790/workflows?limit=200" -o "$tmp/workflows.json" || echo '{}' > "$tmp/workflows.json"
+
+node -e '
+const fs = require("fs");
+const [out, count, dir] = process.argv.slice(1);
+const raw = JSON.parse(fs.readFileSync(dir + "/sessions.json", "utf8"));
+const wf = JSON.parse(fs.readFileSync(dir + "/workflows.json", "utf8"));
+const runs = (Array.isArray(wf) ? wf : wf.items || wf.runs || [])
+  .filter((r) => r.workflowId === "session-steward")
+  .sort((a, b) => String(b.startedAt).localeCompare(String(a.startedAt)));
+const lastRun = runs[0];
+const ts = (s) => Date.parse(s.lastActivityAt || s.lastOutputAt || s.startedAt || 0) || 0;
+const sessions = raw.sessions
+  .filter((s) => s.kind === "agent-cli")
+  .sort((a, b) => ts(b) - ts(a))
+  .slice(0, Number(count));
+const cell = (v) => String(v ?? "").replace(/\|/g, "\\|").replace(/\s+/g, " ").trim();
+const idle = (s) => {
+  const sec = s.secondsSinceLastActivity ?? (Date.now() - ts(s)) / 1000;
+  if (sec < 3600) return Math.round(sec / 60) + "m";
+  if (sec < 86400) return Math.round(sec / 3600) + "h";
+  return Math.round(sec / 86400) + "d";
+};
+const status = (s) =>
+  s.status + (s.busy ? " (busy)" : "") + (s.awaitingInput ? " (awaiting input)" : "");
+const flag = (s) =>
+  s.wrapupFlag ? s.wrapupFlag.verdict + (s.wrapupFlag.note ? ": " + s.wrapupFlag.note : "") : "";
+const outcome = (s) => {
+  const o = s.outcome;
+  if (!o) return "";
+  const t = o.termination;
+  return [o.status, t && t.status + (t.reason ? " (" + t.reason + ")" : "")].filter(Boolean).join(" / ");
+};
+const rows = sessions.map((s) =>
+  "| " +
+  [
+    s.id,
+    cell(s.label || s.title),
+    s.adapterSlug || "-",
+    cell(s.model || s.activeModel || "-"),
+    status(s),
+    idle(s),
+    s.parentSessionId || "",
+    cell(flag(s)),
+    cell(outcome(s)),
+    cell((s.activitySummary?.text || "").slice(0, 100)),
+  ].join(" | ") +
+  " |",
+);
+const flagged = sessions.filter((s) => s.wrapupFlag).length;
+const md = [
+  "# Session snapshot — " + new Date().toISOString(),
+  "",
+  "Last " + rows.length + " agent sessions by activity (of " + raw.sessions.length +
+    " daemon sessions). Steward-flagged: " + flagged + ".",
+  "Last steward run: " + (lastRun ? lastRun.runId + " (" + lastRun.status + ", " + lastRun.startedAt + ")" : "none found"),
+  "Generated by scripts/sessions-snapshot.sh — do not hand-edit.",
+  "",
+  "| id | label | adapter | model | status | idle | parent | steward flag | outcome | last summary |",
+  "|---|---|---|---|---|---|---|---|---|---|",
+  ...rows,
+  "",
+].join("\n");
+fs.writeFileSync(out, md);
+console.log("wrote", out, "(" + rows.length + " sessions, " + flagged + " flagged)");
+' "$out" "$count" "$tmp"

package/session-steward/skill/SKILL.md

@@ -0,0 +1,74 @@
+---
+name: session-steward
+description: Wrap up idle agentproto agent sessions — classify them, close the safe ones, judge the ambiguous ones. Use when the user says "clean up idle sessions", "run the steward", "close finished sessions", or asks which sessions are still needed. Dry run by default; closing (--apply) mutates daemon state.
+---
+
+# Session Steward
+
+The steward wraps up idle agent sessions. It classifies them with
+`session_wrapup_plan`, closes the rule-certain ones, and sends the ambiguous
+ones through a cheap judge (Jev classifier, fallback: a one-shot LLM agent).
+Dry run by default — nothing is closed unless `--apply`.
+
+## Run it
+
+Prefer the CLI (it installs/updates the app and runs the workflow):
+
+```bash
+agentproto steward --wait
+```
+
+Variants:
+
+```bash
+agentproto steward --wait                          # dry run: plan + verdicts + report
+agentproto steward --apply --wait                  # close/flag confident verdicts
+agentproto steward --apply --wait --idle 60        # stricter idle threshold (minutes)
+agentproto steward --apply --wait --min-confidence 0.9
+agentproto steward --apply --wait --judge agent    # force the LLM judge lane
+agentproto steward --ask-sessions --wait           # ask low-confidence sessions directly
+```
+
+`--wait` blocks until the report is ready (a run takes ~1-3 min depending on
+candidate count). Without it, poll with `workflow_status` on the returned
+runId.
+
+## Read the report
+
+The final step output is a markdown table: class (close/stuck/judge),
+session label + id, idle time, RAM, verdict, confidence, reason, action.
+Key reading rules:
+
+- `close` rows are safe to auto-close; `judge` rows are what the judge saw.
+- Verdicts: `done|abandoned|blocked|needs-input|active`. Only confident
+  `done`/`abandoned` close (sessions stay resumable; transcripts preserved).
+  `blocked`/`needs-input` only get flagged, never closed.
+- A judge error never closes anything. If many verdicts come back
+  `active` confidence 0, the judge lane failed (check Jev key config
+  `jev.apiKey` in ~/.agentproto/config.json, env `JEV_API_KEY` fallback).
+- RAM freed / still held is summarized at the end.
+
+## Session snapshot (browsing aid)
+
+`scripts/sessions-snapshot.sh` dumps the 50 most recently active daemon agent
+sessions to a markdown table — id, label, adapter, model, status, idle time,
+parent, steward flag, outcome, last summary, plus the last steward run. It
+reads the daemon's HTTP API (`GET /sessions`, `GET /workflows`) and writes a
+generated file; it never mutates daemon state, so it is safe to run any time.
+
+```bash
+./scripts/sessions-snapshot.sh [out.md] [count]
+# defaults: data/sessions-latest.md, 50
+```
+
+The output lands under `data/` (git-ignored — it is a regenerated snapshot,
+never committed). Use it to eyeball what the steward is about to classify
+before running with `--apply`.
+
+## Rules
+
+- NEVER run with `--apply` without explicit user go-ahead. Dry run first,
+  show the report, then apply.
+- Never judge the calling session — the CLI already excludes it.
+- If a session is mid-turn, busy, or has background tasks, the plan skips
+  it; re-running later is fine and idempotent.