@monster-orange/den 0.4.21 → 0.4.23

package/src/shared/agents/rotate-settings.ts

@@ -0,0 +1,309 @@
+/**
+ * D28: session-rotation settings and where each comes from.
+ *
+ *   after_compactions  a whole number (1–100), or "never"; default 3
+ *   on_due             auto | ask | off; default auto
+ *                        auto: Den asks the agent for its handoff at its next
+ *                              idle and relaunches it from it by itself
+ *                        ask:  the callout's buttons (Relaunch now, Write
+ *                              handoff, Keep this conversation, Settings)
+ *                        off:  nothing happens; the count is still shown
+ *   on_pr_merged       true | false; default true
+ *
+ * Scopes, the most specific wins, each key on its own:
+ *   agent › persona in a workspace › persona › workspace › service (the
+ *   workspace service whose folder holds the agent's) › install (Settings ›
+ *   Agents › Rotation, this machine) › org (`agents.rotate` in the org
+ *   config) › Den's default.
+ *
+ * The install value and every override live in
+ * `<stateDir>/agent-rotation.json` (0600; never under agents/, where every
+ * file is an agent's record). The org value is the org config's.
+ */
+import * as fs from "fs";
+import * as path from "path";
+import { writePrivate } from "./records.js";
+
+export type OnDue = "auto" | "ask" | "off";
+
+/** One scope's settings, as written: any key may be absent. */
+export interface RotateValues {
+  after_compactions?: number | "never";
+  on_due?: OnDue;
+  on_pr_merged?: boolean;
+}
+
+export type RotateKey = keyof RotateValues;
+export const ROTATE_KEYS: readonly RotateKey[] = [
+  "after_compactions",
+  "on_due",
+  "on_pr_merged",
+];
+
+/** The scopes an override can be set at (most specific first). */
+export const OVERRIDE_SCOPES = [
+  "agent",
+  "persona-workspace",
+  "persona",
+  "workspace",
+  "service",
+] as const;
+export type OverrideScope = (typeof OVERRIDE_SCOPES)[number];
+export type RotateScope = OverrideScope | "install" | "org" | "default";
+
+export const ROTATE_DEFAULTS: Required<RotateValues> = {
+  after_compactions: 3,
+  on_due: "auto",
+  on_pr_merged: true,
+};
+
+/** `<stateDir>/agent-rotation.json`. */
+export interface RotateFile {
+  install?: RotateValues;
+  overrides?: Partial<Record<OverrideScope, Record<string, RotateValues>>>;
+}
+
+/** Who an agent is, for resolving its settings. */
+export interface RotateSubject {
+  agent: string;
+  persona: string;
+  workspace: string;
+  /** The workspace service whose folder holds the agent's, if any. */
+  service?: string;
+  /** A standing persona (planner, orchestrator): `standing: false` in the org config keeps it from rotating. */
+  standing?: boolean;
+}
+
+/** Where a value came from: "default", or a scope and its target. */
+export interface RotateSource {
+  scope: RotateScope;
+  /** The agent id, persona, "persona@workspace", workspace or service. */
+  target?: string;
+}
+
+export interface EffectiveRotate {
+  /** 0: never rotates. */
+  afterCompactions: number;
+  onDue: OnDue;
+  onPrMerged: boolean;
+  source: Record<RotateKey, RotateSource>;
+}
+
+/** The org config's `agents.rotate`, checked (den-config.ts). */
+export interface OrgRotate extends RotateValues {
+  /** Dropped by D28 (persona scope replaces it); still honoured. */
+  standing?: boolean;
+}
+
+export const rotateFilePath = (stateDir: string) =>
+  path.join(stateDir, "agent-rotation.json");
+
+/**
+ * One value checked: the problem in words, or null. `after_compactions`
+ * takes 1–100 or "never" (0 also means never, from the CLI).
+ */
+export function checkRotateValue(key: string, v: unknown): string | null {
+  if (key === "after_compactions")
+    return v === "never" ||
+      (typeof v === "number" && Number.isInteger(v) && v >= 1 && v <= 100)
+      ? null
+      : `after_compactions: a whole number from 1 to 100, or never (got ${JSON.stringify(v)})`;
+  if (key === "on_due")
+    return v === "auto" || v === "ask" || v === "off"
+      ? null
+      : `on_due: auto, ask or off (got ${JSON.stringify(v)})`;
+  if (key === "on_pr_merged")
+    return typeof v === "boolean"
+      ? null
+      : `on_pr_merged: true or false (got ${JSON.stringify(v)})`;
+  return `${key}: unknown key (takes ${ROTATE_KEYS.join(", ")})`;
+}
+
+/** A command-line value as the key takes it ("3", "never", "ask", "false"). */
+export function parseRotateValue(key: string, raw: string): unknown {
+  if (key === "after_compactions")
+    return raw === "never" || raw === "0"
+      ? "never"
+      : /^\d+$/.test(raw)
+        ? Number(raw)
+        : raw;
+  if (key === "on_pr_merged")
+    return raw === "true" ? true : raw === "false" ? false : raw;
+  return raw;
+}
+
+/** Only the valid keys of `v` (a bad file never breaks an agent). */
+function cleanValues(v: unknown): RotateValues {
+  const out: RotateValues = {};
+  if (!v || typeof v !== "object" || Array.isArray(v)) return out;
+  for (const k of ROTATE_KEYS) {
+    const x = (v as Record<string, unknown>)[k];
+    if (x !== undefined && checkRotateValue(k, x) === null)
+      (out as Record<string, unknown>)[k] = x;
+  }
+  return out;
+}
+
+/** agent-rotation.json, cleaned; {} when absent or unreadable. */
+export function readRotateFile(stateDir: string): RotateFile {
+  let v: unknown;
+  try {
+    v = JSON.parse(fs.readFileSync(rotateFilePath(stateDir), "utf-8"));
+  } catch {
+    return {};
+  }
+  if (!v || typeof v !== "object" || Array.isArray(v)) return {};
+  const o = v as Record<string, unknown>;
+  const out: RotateFile = {};
+  const inst = cleanValues(o.install);
+  if (Object.keys(inst).length) out.install = inst;
+  if (o.overrides && typeof o.overrides === "object") {
+    const ov: RotateFile["overrides"] = {};
+    for (const scope of OVERRIDE_SCOPES) {
+      const byTarget = (o.overrides as Record<string, unknown>)[scope];
+      if (!byTarget || typeof byTarget !== "object") continue;
+      for (const [target, vals] of Object.entries(byTarget)) {
+        const c = cleanValues(vals);
+        if (Object.keys(c).length) (ov[scope] ??= {})[target] = c;
+      }
+    }
+    if (Object.keys(ov).length) out.overrides = ov;
+  }
+  return out;
+}
+
+export function writeRotateFile(stateDir: string, f: RotateFile): void {
+  fs.mkdirSync(path.dirname(rotateFilePath(stateDir)), {
+    recursive: true,
+    mode: 0o700,
+  });
+  writePrivate(rotateFilePath(stateDir), JSON.stringify(f, null, 2) + "\n");
+}
+
+/**
+ * Set (or with `value` undefined, clear) one key at one scope. `scope`
+ * "install" takes no target. Throws, naming the problem, on a bad key or
+ * value. Returns the file as written.
+ */
+export function setRotateValue(
+  stateDir: string,
+  scope: OverrideScope | "install",
+  target: string | undefined,
+  key: string,
+  value: unknown,
+): RotateFile {
+  if (value !== undefined) {
+    const bad = checkRotateValue(key, value);
+    if (bad) throw new Error(bad);
+  } else if (!(ROTATE_KEYS as readonly string[]).includes(key))
+    throw new Error(checkRotateValue(key, undefined)!);
+  if (scope !== "install" && !target)
+    throw new Error(`a ${scope} override needs the ${scope} it is for`);
+  const f = readRotateFile(stateDir);
+  const k = key as RotateKey;
+  const apply = (vals: RotateValues | undefined): RotateValues => {
+    const next: RotateValues = { ...(vals ?? {}) };
+    if (value === undefined) delete next[k];
+    else (next as Record<string, unknown>)[k] = value;
+    return next;
+  };
+  if (scope === "install") {
+    const next = apply(f.install);
+    if (Object.keys(next).length) f.install = next;
+    else delete f.install;
+  } else {
+    const ov = (f.overrides ??= {});
+    const byTarget = (ov[scope] ??= {});
+    const next = apply(byTarget[target!]);
+    if (Object.keys(next).length) byTarget[target!] = next;
+    else delete byTarget[target!];
+    if (!Object.keys(byTarget).length) delete ov[scope];
+    if (!Object.keys(ov).length) delete f.overrides;
+  }
+  writeRotateFile(stateDir, f);
+  return f;
+}
+
+/** The target an override scope uses for `s`, or undefined. */
+export function targetFor(
+  scope: OverrideScope,
+  s: RotateSubject,
+): string | undefined {
+  switch (scope) {
+    case "agent":
+      return s.agent;
+    case "persona-workspace":
+      return `${s.persona}@${s.workspace}`;
+    case "persona":
+      return s.persona;
+    case "workspace":
+      return s.workspace;
+    case "service":
+      return s.service;
+  }
+}
+
+/** Agent `s`'s settings, each key from the most specific scope that sets it. */
+export function resolveRotate(
+  s: RotateSubject,
+  file: RotateFile,
+  org: OrgRotate | undefined,
+): EffectiveRotate {
+  const layers: { source: RotateSource; values: RotateValues }[] = [];
+  for (const scope of OVERRIDE_SCOPES) {
+    const target = targetFor(scope, s);
+    const values = target ? file.overrides?.[scope]?.[target] : undefined;
+    if (values) layers.push({ source: { scope, target }, values });
+  }
+  if (file.install)
+    layers.push({ source: { scope: "install" }, values: file.install });
+  if (org) {
+    const values: RotateValues = { ...org };
+    delete (values as OrgRotate).standing;
+    // den#4's `standing: false`: standing personas never rotate.
+    if (org.standing === false && s.standing)
+      values.after_compactions = "never";
+    layers.push({ source: { scope: "org" }, values });
+  }
+  const pick = <K extends RotateKey>(k: K) => {
+    for (const l of layers)
+      if (l.values[k] !== undefined)
+        return {
+          v: l.values[k] as Required<RotateValues>[K],
+          source: l.source,
+        };
+    return {
+      v: ROTATE_DEFAULTS[k],
+      source: { scope: "default" } as RotateSource,
+    };
+  };
+  const a = pick("after_compactions");
+  const o = pick("on_due");
+  const p = pick("on_pr_merged");
+  return {
+    afterCompactions: a.v === "never" ? 0 : a.v,
+    onDue: o.v,
+    onPrMerged: p.v,
+    source: {
+      after_compactions: a.source,
+      on_due: o.source,
+      on_pr_merged: p.source,
+    },
+  };
+}
+
+/** "persona planner", "agent art", "this install", "org config", "default". */
+export function sourceText(src: RotateSource): string {
+  switch (src.scope) {
+    case "default":
+      return "default";
+    case "install":
+      return "this install";
+    case "org":
+      return "org config";
+    case "persona-workspace":
+      return `persona ${src.target!.replace("@", " in ")}`;
+    default:
+      return `${src.scope} ${src.target}`;
+  }
+}

package/src/shared/agents/rotation.ts

@@ -56,6 +56,13 @@ export interface RotationState {
   /** Set when a trigger fired. */
   due?: RotateReason;
   dueAt?: string;
+  /** D28: how many times Den asked for the handoff, and the last time. */
+  asked?: number;
+  askedAt?: string;
+  /** D28: auto gave up asking (2 asks, still no handoff): ask mode. */
+  fellBack?: boolean;
+  /** D28 "Relaunch now" before a handoff: relaunch once it passes, whatever on_due says. */
+  relaunchWanted?: boolean;
 }
 
 /** `agents.rotate` with its defaults applied. */
@@ -80,6 +87,8 @@ export interface RotationEntry {
   compactions: number;
   /** The conversation that ended (its resume token). */
   conversation?: string;
+  /** D28: Den relaunched it by itself (on_due auto). */
+  auto?: boolean;
 }
 
 /** The compactions after which `persona` rotates; 0: it never does. */
@@ -119,6 +128,10 @@ export function readRotation(filesDir: string): RotationState | null {
   if (typeof o.pendingTrigger === "string") s.pendingTrigger = o.pendingTrigger;
   if (o.due === "compactions" || o.due === "pr-merged") s.due = o.due;
   if (typeof o.dueAt === "string") s.dueAt = o.dueAt;
+  if (count(o.asked)) s.asked = count(o.asked);
+  if (typeof o.askedAt === "string") s.askedAt = o.askedAt;
+  if (o.fellBack === true) s.fellBack = true;
+  if (o.relaunchWanted === true) s.relaunchWanted = true;
   return s;
 }
 
@@ -235,6 +248,51 @@ export function markDue(
   return true;
 }
 
+/**
+ * D28 "Keep this conversation": the count starts again from 0 for the
+ * conversation it has, and nothing is due. Returns false with no state.
+ */
+export function keepConversation(filesDir: string): boolean {
+  const s = readRotation(filesDir);
+  if (!s) return false;
+  writeRotation(filesDir, {
+    ...(s.conversation ? { conversation: s.conversation } : {}),
+    compactions: 0,
+    after: s.after,
+  });
+  return true;
+}
+
+/** D28: one more ask for the handoff, noted; `relaunch`: Relaunch now asked. */
+export function noteAsked(
+  filesDir: string,
+  now: Date = new Date(),
+  relaunch = false,
+): RotationState | null {
+  const s = readRotation(filesDir);
+  if (!s) return null;
+  const next: RotationState = {
+    ...s,
+    asked: (s.asked ?? 0) + 1,
+    askedAt: now.toISOString(),
+    ...(relaunch ? { relaunchWanted: true } : {}),
+  };
+  writeRotation(filesDir, next);
+  return next;
+}
+
+/** D28: auto gave up asking; the callout's buttons take over. */
+export function noteFellBack(filesDir: string): void {
+  const s = readRotation(filesDir);
+  if (s && !s.fellBack) writeRotation(filesDir, { ...s, fellBack: true });
+}
+
+/** D28: the limit the hook counts against, when the settings changed. */
+export function syncAfter(filesDir: string, after: number): void {
+  const s = readRotation(filesDir);
+  if (s && s.after !== after) writeRotation(filesDir, { ...s, after });
+}
+
 /** Clear a rotation due for `reason` (a merge mark gh no longer confirms). */
 export function clearDue(filesDir: string, reason: RotateReason): boolean {
   const s = readRotation(filesDir);
@@ -274,8 +332,31 @@ export function readHandoff(filesDir: string): {
   return { status: r.ok ? "ok" : "invalid", text, problems: r.problems };
 }
 
+/**
+ * D28: an agent's effective rotation settings (rotate-settings.ts), when
+ * the caller resolved them; without, the state's own limit and den#4's
+ * rules apply.
+ */
+export interface RotationPolicy {
+  /** 0: never rotates. */
+  afterCompactions: number;
+  onDue: "auto" | "ask" | "off";
+  onPrMerged: boolean;
+  /** Where each value comes from, in words ("persona planner"). */
+  from?: { after_compactions: string; on_due: string; on_pr_merged: string };
+}
+
 /** An agent's rotation, as the Agents page and the CLI show it. */
 export interface RotationInfo {
+  /** D28: what happens when it is due, and where the settings come from. */
+  onDue?: RotationPolicy["onDue"];
+  from?: RotationPolicy["from"];
+  /** D28: Den asked it for its handoff this many times (auto). */
+  asked?: number;
+  /** D28: auto fell back to ask (the handoff still failed after 2 asks). */
+  fellBack?: boolean;
+  /** D28: Relaunch now was asked before the handoff: Den relaunches once it passes. */
+  relaunchWanted?: boolean;
   /** Why it rotates, when a trigger fired. */
   due?: RotateReason;
   compactions: number;
@@ -295,20 +376,44 @@ export interface RotationInfo {
 export function rotationInfo(
   stateDir: string,
   rec: AgentRecord,
+  policy?: RotationPolicy,
 ): RotationInfo | null {
   const files = agentFilesDir(stateDir, rec.id);
-  const s = readRotation(files);
-  if (!s) return null;
-  if (s.conversation && rec.resumeToken && s.conversation !== rec.resumeToken)
+  const read = readRotation(files);
+  if (!read) return null;
+  if (
+    read.conversation &&
+    rec.resumeToken &&
+    read.conversation !== rec.resumeToken
+  )
     return null;
+  // D28: the limit in force now, not the one the launch counted against.
+  const s: RotationState = policy
+    ? { ...read, after: policy.afterCompactions }
+    : read;
+  if (
+    policy &&
+    s.after > 0 &&
+    s.compactions < s.after &&
+    s.due === "compactions"
+  ) {
+    delete s.due;
+  }
+  if (policy && !policy.onPrMerged && s.due === "pr-merged") delete s.due;
+  const merged = policy ? policy.onPrMerged : true;
   const due =
     dueFor(s) ??
-    (s.after > 0 && rec.outcome?.prMerged ? "pr-merged" : undefined);
+    (s.after > 0 && merged && rec.outcome?.prMerged ? "pr-merged" : undefined);
   const h = due
     ? readHandoff(files)
     : { status: "missing" as const, problems: [] };
   return {
     ...(due ? { due } : {}),
+    ...(policy ? { onDue: policy.onDue } : {}),
+    ...(policy?.from ? { from: policy.from } : {}),
+    ...(read.asked ? { asked: read.asked } : {}),
+    ...(read.fellBack ? { fellBack: true } : {}),
+    ...(read.relaunchWanted ? { relaunchWanted: true } : {}),
     compactions: s.compactions,
     after: s.after,
     handoff: h.status,
@@ -346,7 +451,7 @@ export function rotationInstruction(
   const why =
     reason === "pr-merged"
       ? "its pull request merged"
-      : `it has compacted ${compactions} times`;
+      : `it has compacted ${compactions === 1 ? "once" : `${compactions} times`}`;
   return [
     `Den: this session is done, because ${why} (session rotation).`,
     `Write your handoff now, to ${handoffFile(filesDir)}, with these headings, each filled in:`,

package/src/shared/agents/runtime.ts

@@ -120,6 +120,12 @@ export interface LaunchInput {
    * Only a runtime with `firstPrompt: true` is given one.
    */
   firstPrompt?: string;
+  /**
+   * D24: the name other sessions see this one by (peerSessionName:
+   * `<cli>-<ws>:<name>`). A runtime that can name its session (den-claude:
+   * `--name`) does, at launch and at resume.
+   */
+  sessionLabel?: string;
 }
 
 export interface LaunchOutput {

package/src/shared/agents/session-name.ts

@@ -12,7 +12,10 @@
  *     token: Start fresh forgets it). An adapter that fails or throws is no
  *     name; it never breaks the list.
  *
- * Den never writes a name back into the runtime.
+ * D24: Den names the runtime's session for other sessions to see
+ * (peerSessionName: `<cli>-<ws>:<name>`, Claude Code's `--name`) at launch
+ * and resume. That name read back is Den's own (the record's peerName),
+ * never a rename.
  */
 import * as fs from "fs";
 import * as path from "path";
@@ -71,6 +74,8 @@ function runtimeName(
   } catch {
     name = null;
   }
+  // D24: Den's own --name, read back, is not the runtime's rename.
+  if (name && name === rec.peerName) name = null;
   // null: nothing new (not caught up, not found); the last name stays.
   if (name && name !== seen?.name) {
     seen = { token, name, at: now() };
@@ -83,6 +88,21 @@ function runtimeName(
   return seen;
 }
 
+/**
+ * D24: the name other sessions (ListAgents) see agent `rec` by:
+ * `<cli>-<ws>:<its name, else its id>`. No control characters: it is a
+ * process argument.
+ */
+export function peerSessionName(
+  cli: string,
+  ws: string,
+  rec: Pick<AgentRecord, "id" | "displayName">,
+): string {
+  // eslint-disable-next-line no-control-regex
+  const name = (rec.displayName ?? "").replace(/[\u0000-\u001f\u007f]/g, "");
+  return `${cli}-${ws}:${name.trim() || rec.id}`;
+}
+
 /**
  * The agent's session name: the latest of Den's rename and the runtime's,
  * or undefined when neither has one. Never throws.

package/src/shared/den-config.ts

@@ -21,6 +21,7 @@ import { ConfigError, isConfigError } from "./config-error.js";
 import { validateCatalog, type CatalogEntry } from "./agents/catalog.js";
 import type { Guardrails } from "./agents/guardrails.js";
 import { DEFAULT_ROTATE, type RotateSettings } from "./agents/rotation.js";
+import { checkRotateValue, type OrgRotate } from "./agents/rotate-settings.js";
 import {
   checkCategoriesConfig,
   checkRolesConfig,
@@ -965,6 +966,8 @@ export interface ResolvedAgentsConfig {
   runtimeCatalog: CatalogEntry[];
   /** agents.rotate with its defaults (den#4); unset: DEFAULT_ROTATE. */
   rotate?: RotateSettings;
+  /** D28: agents.rotate as written, the org scope. */
+  rotateOrg?: OrgRotate;
   /** agents.categories (AG-10.5): the distribution's, after Den's. */
   categories?: Category[];
   /** agents.roles (AG-11.1): new roles and Den roles' preset extensions. */
@@ -972,32 +975,41 @@ export interface ResolvedAgentsConfig {
 }
 
 /** `agents.rotate` checked; any other key, or a bad value, throws naming it. */
-function rotateBlock(v: unknown): RotateSettings {
+/**
+ * `agents.rotate` checked, both ways: den#4's settings (afterCompactions 0
+ * for never) and, for D28's scopes, the org's values as written.
+ */
+export function rotateOrgBlock(v: unknown): {
+  settings: RotateSettings;
+  org: OrgRotate;
+} {
   const out: RotateSettings = { ...DEFAULT_ROTATE };
-  if (v === undefined || v === null) return out;
+  const org: OrgRotate = {};
+  if (v === undefined || v === null) return { settings: out, org };
   if (!isMapping(v))
     throw new Error(
-      "agents.rotate: must be a mapping ({ after_compactions: <n>, standing: true|false })",
+      "agents.rotate: must be a mapping ({ after_compactions: <n>|never, on_due: auto|ask|off, on_pr_merged: true|false })",
     );
   for (const [k, x] of Object.entries(v)) {
-    if (k === "after_compactions") {
-      if (typeof x !== "number" || !Number.isInteger(x) || x < 1 || x > 100)
-        throw new Error(
-          `agents.rotate.after_compactions: must be a whole number from 1 to 100 (got ${JSON.stringify(x)})`,
-        );
-      out.afterCompactions = x;
+    if (k === "after_compactions" || k === "on_due" || k === "on_pr_merged") {
+      const bad = checkRotateValue(k, x);
+      if (bad) throw new Error(`agents.rotate.${bad}`);
+      (org as Record<string, unknown>)[k] = x;
+      if (k === "after_compactions")
+        out.afterCompactions = x === "never" ? 0 : (x as number);
     } else if (k === "standing") {
       if (typeof x !== "boolean")
         throw new Error(
           `agents.rotate.standing: must be true or false (got ${JSON.stringify(x)})`,
         );
       out.standing = x;
+      org.standing = x;
     } else
       throw new Error(
-        `agents.rotate.${k}: unknown key (takes after_compactions, standing)`,
+        `agents.rotate.${k}: unknown key (takes after_compactions, on_due, on_pr_merged)`,
       );
   }
-  return out;
+  return { settings: out, org };
 }
 
 /** An agent id or workspace name: what WORKSPACE_NAME_RE accepts. */
@@ -1060,7 +1072,10 @@ export function readAgentsConfig(
       raw.runtime_catalog,
       "agents.runtime_catalog",
     ),
-    rotate: rotateBlock(raw.rotate),
+    ...(() => {
+      const r = rotateOrgBlock(raw.rotate);
+      return { rotate: r.settings, rotateOrg: r.org };
+    })(),
   };
   out.categories = checkCategoriesConfig(raw.categories);
   out.roles = checkRolesConfig(raw.roles, [