@cohortapp/agent-sdk 2.16.0 → 2.17.0

package/scripts/daemon/dispatcher.mjs

@@ -143,6 +143,125 @@ import { budgetLadder, spawnKnobsFor } from "../../lib/model-router/economics.mj
 // AsyncLocalStorage cannot cross the proc-event boundary) + the v2 decision_id.
 // emitEvent is fail-open (never throws), so this is purely additive telemetry.
 import { emitEvent, EVENT_TYPES } from "../../lib/diagnostics/events.mjs";
+import {
+  createRouterSync,
+  routingKey as deriveRoutingKey,
+  routerItemFromDaemonItem,
+  claimSession,
+  releaseSession,
+} from "./lib/session-router.mjs";
+import { replyTier } from "../../lib/assurance/tier.mjs";
+
+/**
+ * The reply tier comes from `lib/assurance/tier.mjs` (design §5.1) — the ONE
+ * definition, imported statically now that both halves of the design have
+ * merged.
+ *
+ * There used to be a `localReplyTier` here carrying "the same table" for the
+ * window in which this package shipped before the acknowledgement package. It
+ * was not the same table: it predated the review fix that added
+ * `willSpawnSession !== true` to rule (2), so an item the quick path fell
+ * through on would have been tiered `answer` — total silence — while a long
+ * session ran. The duplicate's own test ("localReplyTier agrees with
+ * lib/assurance/tier.mjs wherever that module exists") is what caught it at
+ * the merge, which is the only reason the divergence is a footnote and not an
+ * outage. Two copies of one decision is the bug; there is now one.
+ */
+
+/** The reply tier → the router task class that carries its effort knobs. */
+const TASK_CLASS_BY_TIER = Object.freeze({
+  answer: "session.answer",
+  work: "session.responder",
+  plan: "session.plan",
+});
+
+/** Rungs, as `lib/execution/route.RUNGS` numbers them. */
+const ANSWER_MAX_RUNG = 1;
+const PLAN_MIN_RUNG = 3;
+
+/**
+ * A rung worth reasoning from, or null. An out-of-range value, a string "3" or
+ * a NaN is a stale field, and reading one as a rung would let a typo pick the
+ * turn's effort. Same coercion as `lib/assurance/tier.mjs#routedRung`.
+ */
+function routedRung(rung) {
+  if (typeof rung !== "number" || !Number.isInteger(rung)) return null;
+  return rung < 0 || rung > 5 ? null : rung;
+}
+
+
+/**
+ * The routed execution rung for an item, or null.
+ *
+ * `agent-daemon.mjs:617` stamps the ladder's decision onto `item.execution`
+ * precisely so everything downstream can see which rung the turn is serving.
+ * The classifier emits no `rung` field of its own, so reading `classResult.rung`
+ * finds `undefined` forever — which would make `session.answer`'s knobs dead
+ * code and the tier table a decoration.
+ */
+export function rungForItem(item) {
+  const ex = item && typeof item === "object" ? item.execution : null;
+  if (ex && typeof ex === "object") {
+    const r = routedRung(ex.rung);
+    if (r != null) return r;
+  }
+  return routedRung(item && item.rung);
+}
+
+/**
+ * The task class for this spawn. Was hardcoded `"session.responder"`, so every
+ * session took the same 40-turn, null-effort knobs no matter what was asked
+ * (design §3 R13).
+ *
+ * @param {object} classResult
+ * @param {object} [item] the inbox item, which carries the ladder's decision
+ */
+export function taskClassFor(classResult, item = null) {
+  const c = classResult || {};
+  const args = {
+    answerable: c.answerable,
+    action: c.action,
+    priority: c.priority,
+    rung: rungForItem(item) ?? routedRung(c.rung),
+    // DELIBERATELY LEFT UNKNOWN, even though this function is only ever called
+    // on the spawn path and `true` is the literally accurate value.
+    //
+    // `replyTier` answers two different questions and the spawn flag matters to
+    // only one of them:
+    //
+    //   "will the reply arrive in this turn?"  — the ACKNOWLEDGEMENT question.
+    //      A spawning item must never be tiered `answer`, because `answer`
+    //      means total silence and the premise (an in-turn reply) is false.
+    //      `assurance.mjs` asserts `willSpawnSession: true` for exactly that.
+    //
+    //   "how hard is this ask?"                — the EFFORT question, ours.
+    //      Whether a session is spawning says nothing about it. A cheap,
+    //      answerable, rung-0 ask deserves `session.answer`'s knobs whether it
+    //      is answered in-turn or in a session.
+    //
+    // Asserting `true` here collapsed the two: rule (2) requires
+    // `willSpawnSession !== true`, so on the spawn path — the only path this
+    // function has — NOTHING could ever reach the `answer` tier and the
+    // `session.answer` effort class became unreachable. Caught at the merge by
+    // "taskClassFor maps each tier onto the class that carries its knobs".
+    // Leaving it unknown asks the tier the question this caller actually has.
+    willSpawnSession: undefined,
+  };
+  // A tier module that throws must not stop a dispatch: `work` is the tier the
+  // flood was made of and the one that speaks at most once, so it is the right
+  // thing to fall back to.
+  let tier = "work";
+  try { tier = replyTier(args) || "work"; } catch { tier = "work"; }
+  return TASK_CLASS_BY_TIER[tier] || "session.responder";
+}
+
+/**
+ * The session-continuity registry, shared with `responder.mjs` — same file,
+ * same key function, same decision. Synchronous because `spawnSession` builds
+ * its argv and spawns in one pass; see `createRouterSync`'s note.
+ */
+const SESSION_REGISTRY_PATH = join(AGENT_REPO_DIR, "state", "daemon", "session-router-registry.json");
+const sessionRouter = createRouterSync({ registryPath: SESSION_REGISTRY_PATH });
 // Lazy + cached so a misconfigured YAML doesn't break agents that didn't
 // opt in. The cache is invalidated only on daemon restart.
 let _routingConfigCache;
@@ -1167,17 +1286,21 @@ function currentBudgetBand() {
  * @param {object} classResult
  * @param {string} source
  * @param {string} fallbackModel  the coarse sonnet/opus class for the no-config path
+ * @param {object} [item]         the inbox item, which carries the routed rung
  */
-function resolveSpawnTarget(routingConfig, routingRequest, classResult, source, fallbackModel) {
+function resolveSpawnTarget(routingConfig, routingRequest, classResult, source, fallbackModel, item = null) {
   // No config at all → stock Claude-CLI-on-Max behaviour (unchanged).
   if (!routingConfig) {
-    return { modelFlag: fallbackModel, envForSpawn: {}, decisionId: null, backend: null, model: null, transport: "anthropic-cli", maxTurns: null, effort: null, agentsJson: null, explain: null, decision: null };
+    return { taskClass: taskClassFor(classResult, item), modelFlag: fallbackModel, envForSpawn: {}, decisionId: null, backend: null, model: null, transport: "anthropic-cli", maxTurns: null, effort: null, agentsJson: null, explain: null, decision: null };
   }
 
   // v2 path — resolveChain produces a full RouteDecision.
   if (routingConfig.schema_version === 2) {
     try {
-      const taskClass = "session.responder";
+      // The task class carries the spawn knobs (`spawnKnobsFor`), so hardcoding
+      // one made `effort` always null and `maxTurns` always 40. It is now the
+      // reply tier — see `taskClassFor`.
+      const taskClass = taskClassFor(classResult, item);
       const req = {
         ...routingRequest,
         task_class: taskClass,
@@ -1194,6 +1317,7 @@ function resolveSpawnTarget(routingConfig, routingRequest, classResult, source,
         const knobs = spawnKnobsFor(taskClass);
         const sa = decision.spawnArgs || {};
         return {
+          taskClass,
           modelFlag: sa.modelFlag || decision.chosen.model || fallbackModel,
           envForSpawn: decision.envForSpawn || {},
           decisionId: decision.decision_id || null,
@@ -1216,9 +1340,10 @@ function resolveSpawnTarget(routingConfig, routingRequest, classResult, source,
   // v1 path — resolveBackend → modelFlagFor (preserved verbatim).
   const resolved = resolveBackend(routingRequest, { config: routingConfig });
   if (!resolved) {
-    return { modelFlag: fallbackModel, envForSpawn: {}, decisionId: null, backend: null, model: null, transport: "anthropic-cli", maxTurns: null, effort: null, agentsJson: null, explain: null, decision: null };
+    return { taskClass: taskClassFor(classResult, item), modelFlag: fallbackModel, envForSpawn: {}, decisionId: null, backend: null, model: null, transport: "anthropic-cli", maxTurns: null, effort: null, agentsJson: null, explain: null, decision: null };
   }
   return {
+    taskClass: taskClassFor(classResult, item),
     modelFlag: modelFlagFor(resolved, routingRequest),
     envForSpawn: resolved.envForSpawn || {},
     decisionId: null,
@@ -1275,13 +1400,57 @@ function spawnSession(entry) {
   // default exactly. NEVER throws (resolveSpawnTarget degrades internally).
   const routingConfig = getRoutingConfig();
   const routingRequest = requestFromClassifierResult(classResult, { source, role: "responder" });
-  const target = resolveSpawnTarget(routingConfig, routingRequest, classResult, source, model);
+  const target = resolveSpawnTarget(routingConfig, routingRequest, classResult, source, model, item);
   const effectiveModelFlag = target.modelFlag || model;
 
-  // WS4: pre-mint a stable Claude session id so a crash/reboot mid-flight can
-  // be resumed deterministically with `claude --print --resume <id>`. (Same
-  // mechanism the responder already uses; safe in --print text mode.)
-  const claudeSessionId = randomUUID();
+  // Session continuity. A fresh `randomUUID()` per dispatch meant every full
+  // session in a live thread started COLD — the agent re-read the room, re-did
+  // the orientation work, and answered a follow-up as if it were an opening
+  // (design §3 R10). The router the responder already consults keys the
+  // conversation; a follow-up inside the TTL resumes the same session id, which
+  // in this daemon IS continuation (`--session-id <id> <prompt>`, never
+  // `--resume` — see the resume-pending notes above).
+  //
+  // Inbox only. Backlog work is not a conversation, and keying it would put
+  // unrelated items in one session.
+  //
+  // Everything here is fail-open: no key, an unreadable registry, or a throw
+  // from `routingKey` all fall back to the fresh UUID, which is exactly the
+  // behaviour being replaced. Crash-recovery resume is UNCHANGED — it still
+  // rides `writeResumePending(..., claudeSessionId, ...)` below, with whichever
+  // id this resolved to.
+  //
+  // AND ONE PROCESS PER KEY. `route()` refuses to resume a key this daemon
+  // already has a child on, and the claim below is what tells it so. A burst in
+  // a busy top-level channel — the measured shape: ~38 messages an hour in one
+  // room, where the thread lock does not apply because there is no thread id —
+  // would otherwise put three or four `claude --print --session-id <same id>`
+  // processes on ONE transcript. The later turns spawn cold instead, which is
+  // exactly the pre-router behaviour, and continuity returns on the next turn.
+  let sessionRoutingKey = null;
+  let resumedSessionId = null;
+  if (source === "inbox") {
+    const routerItem = routerItemFromDaemonItem(item);
+    if (routerItem) {
+      try {
+        const candidateKey = deriveRoutingKey(routerItem);
+        const decision = sessionRouter.route(candidateKey);
+        if (claimSession(candidateKey)) {
+          sessionRoutingKey = candidateKey;
+          if (decision.decision === "RESUME" && decision.resumeId) resumedSessionId = decision.resumeId;
+        } else {
+          // Something is already running on this room. Spawn cold, and do NOT
+          // hold the key — the running session owns the registry row, and the
+          // second turn must not overwrite it on close.
+          console.log(`[dispatcher] ${candidateKey} already in flight — spawning cold (no session reuse)`);
+        }
+      } catch (err) {
+        console.warn(`[dispatcher] session routing key failed: ${err.message} — spawning cold`);
+        sessionRoutingKey = null;
+      }
+    }
+  }
+  const claudeSessionId = resumedSessionId || randomUUID();
 
   // The v2 router supplies spawn knobs (SPEC §4.4 / §6.5): --max-turns bounds
   // the session, --effort tunes reasoning where supported, --agents attaches the
@@ -1416,6 +1585,9 @@ function spawnSession(entry) {
     priority: classResult.priority,
     summary: classResult.summary,
     active_count: activeSessions.size,
+    task_class: target.taskClass || null,
+    session_key: sessionRoutingKey,
+    continued: Boolean(resumedSessionId),
   });
 
   // Observability: the interaction's trace_id rode in on item.trace_id (set by
@@ -1448,6 +1620,7 @@ function spawnSession(entry) {
     // happened. Skip to avoid double-count and double-release.
     if (spawnErrorHandled.has(sessionId)) {
       spawnErrorHandled.delete(sessionId);
+      if (sessionRoutingKey) releaseSession(sessionRoutingKey);
       clearResumePending(sessionId); // error path already terminal — no resume
       // The error handler already fired onClose(ok:false) AND emitted
       // session_closed; the single-fire guard makes the onClose a no-op, and we
@@ -1461,6 +1634,31 @@ function spawnSession(entry) {
     recordSession(true, code === 0);
     const duration = ((Date.now() - startTime) / 1000).toFixed(1);
 
+    // Session continuity: a clean exit keeps the key live for the next turn in
+    // this conversation; a non-zero one marks it killed so the next route
+    // returns EPHEMERAL_REPLACE rather than resuming into a broken session.
+    // Best-effort — a registry we cannot write costs continuity, never work.
+    if (sessionRoutingKey) {
+      try {
+        if (code === 0) {
+          sessionRouter.touch(sessionRoutingKey, {
+            claudeSessionId,
+            daemonSessionId: sessionId,
+            model: effectiveModelFlag,
+          });
+        } else {
+          sessionRouter.recordExit(sessionRoutingKey, code);
+        }
+      } catch (err) {
+        console.warn(`[dispatcher] session router update failed for ${sessionRoutingKey}: ${err.message}`);
+      } finally {
+        // The key is free the moment the child is gone — released in a `finally`
+        // so a registry write that throws cannot leave the room permanently
+        // unable to continue a session.
+        releaseSession(sessionRoutingKey);
+      }
+    }
+
     // WS4: a clean exit retires the resume marker (work finished — nothing to
     // resume) and closes the shared 429 breaker. A non-zero exit whose stderr
     // looks like a rate limit opens the breaker so ALL spawn sources back off
@@ -1622,6 +1820,9 @@ function spawnSession(entry) {
     if (source === "inbox") { try { stopTyping(item); } catch { /* */ } }
     // Mark so the trailing proc.on("close") doesn't double-process.
     spawnErrorHandled.add(sessionId);
+    // A spawn that never ran still holds the room's key. Release it here — the
+    // close handler's release is behind an early return on this path.
+    if (sessionRoutingKey) releaseSession(sessionRoutingKey);
     activeSessions.delete(sessionId);
     removeActiveSession(sessionId);
     // Spawn never ran — there is nothing to resume; retire the marker so the