dsh-pause-resume 0.1.0 → 0.3.0

package/lib/probe.js

@@ -1,8 +1,24 @@
 /**
  * What the Harness is doing right now, and how to stop one piece of it without losing the pieces
- * behind it. Only service contracts are used here, and every service is reached through the
- * registry this module is given: one that is missing, or that answers nothing, is a smaller set of
- * work rather than a failed press.
+ * behind it.
+ *
+ * Every fact below is one of the official service contracts, checked against the shipped Harness:
+ * - `agents.get(id)` returns the live Agent object itself, and every goal call takes that object
+ *   (the goal service rejects `{ id }` stand-ins). Enumerating `agents.list()` is therefore both the
+ *   cheapest and the only correct view of "who can run". A session with no live agent cannot be
+ *   running and cannot have an armed goal.
+ * - `sessionController.cancel({ sessionId })` stops one turn and keeps the pending inbox.
+ * - `sessionController.resolveAgent(sessionId)` is the public resume path: it mounts the recorded
+ *   preset and model selection, unlike a raw `agents.resume`.
+ * - `sessionController.prompt(request, signal)` admits one real user message after resuming the
+ *   session itself. The shipped service validates the AbortSignal before it does anything, so the
+ *   second argument is that signal, never the source metadata (the service builds the source).
+ *   That is the only supported way to make a resumed session continue work, so a restore that must
+ *   continue says so with a visible message instead of pretending the turn came back by itself.
+ * - `sessionController.resolveAgent(sessionId)` answers an already live Agent directly and wraps a
+ *   cold one as `{ agent }`, or `{ error }`; both shapes are handled here.
+ * - `goals.pause` / `goals.resume` require the exact current revision, and every transition bumps
+ *   it. The revision captured after pausing is the one a later resume must present.
  */
 
 function service(services, key) {
@@ -13,13 +29,15 @@ function service(services, key) {
   }
 }
 
+/** The live Agent for one session, or undefined. Never a `{ id }` stand-in. */
 function agentOf(services, sessionId) {
   const agents = service(services, 'agents')
   if (agents === undefined || agents === null || typeof agents.get !== 'function') return undefined
   try {
-    const handle = agents.get(sessionId)
-    if (handle === undefined || handle === null) return undefined
-    return handle.agent ?? handle
+    const found = agents.get(sessionId)
+    if (found === undefined || found === null) return undefined
+    if (typeof found.id === 'string' && typeof found.status === 'string') return found
+    return typeof found.agent?.id === 'string' ? found.agent : undefined
   } catch {
     return undefined
   }
@@ -28,7 +46,7 @@ function agentOf(services, sessionId) {
 /**
  * Live agents are the cheap truth for "who is attached right now": a couple of dozen handles in
  * memory, against a listing that walks every session ever recorded on disk. It answers `undefined`
- * when the registry cannot be read, so the listing stays the fallback rather than a second opinion.
+ * when the registry cannot be read, so the caller can tell "nothing live" from "cannot tell".
  */
 function agentsOf(services) {
   const agents = service(services, 'agents')
@@ -36,62 +54,36 @@ function agentsOf(services) {
   try {
     const handles = agents.list()
     if (!Array.isArray(handles)) return undefined
-    const live = handles.map((handle) => handle?.agent ?? handle).filter((agent) => agent !== null && typeof agent?.id === 'string')
-    return live
+    return handles
+      // The row wrapper carries its own `status`; only the agent inside it knows whether a turn is open.
+      .map((handle) => (handle?.agent !== null && typeof handle?.agent === 'object' ? handle.agent : handle))
+      .filter((agent) => agent !== null && agent !== undefined && typeof agent?.id === 'string')
   } catch {
     return undefined
   }
 }
 
-/** One row per attached agent: running says whether its turn is open, and every one is attached. */
-async function attachedRows(services) {
-  const agents = agentsOf(services)
-  if (agents !== undefined) {
-    return agents.map((agent) => ({ sessionId: agent.id, running: agent.status === 'running', agentAvailable: true }))
-  }
-  const rows = await listSessions(services)
-  return rows.filter((row) => row.running === true || row.agentAvailable === true)
-}
-
 /** The session ids whose turn is open right now: the heartbeat's only question. */
-export async function listRunning(services) {
+export function listRunning(services) {
   const agents = agentsOf(services)
-  if (agents !== undefined) return agents.filter((agent) => agent.status === 'running').map((agent) => agent.id)
-  const rows = await listSessions(services)
-  return rows.filter((row) => row.running === true).map((row) => row.sessionId)
+  if (agents === undefined) return []
+  return agents.filter((agent) => agent.status === 'running').map((agent) => agent.id)
 }
 
-/**
- * The goal service addresses one live agent, and every agent it accepts names itself by session
- * id, so a session id is the whole handle. It throws for an agent that is not live: that is the
- * ordinary answer for a closed session, not an error worth surfacing.
- */
-function goalAgent(sessionId) {
-  return { id: sessionId }
-}
-
-async function goalOf(services, sessionId) {
+/** The goal view for one exact live agent, or undefined. The goal service throws for a dead agent. */
+function goalView(services, agent) {
   const goals = service(services, 'goals')
   if (goals === undefined || goals === null || typeof goals.get !== 'function') return undefined
   try {
-    const view = await goals.get(goalAgent(sessionId))
+    const view = goals.get(agent)
     return view === undefined || view === null ? undefined : view
   } catch {
     return undefined
   }
 }
 
-/** The listing service answers `{ items }` through its remote facade and a bare array in tests. */
-async function listSessions(services) {
-  const controller = service(services, 'sessionController')
-  if (controller === undefined || controller === null || typeof controller.list !== 'function') return []
-  const value = await controller.list({})
-  const rows = Array.isArray(value) ? value : value?.items ?? value?.sessions ?? []
-  return rows.filter((row) => row !== null && typeof row?.sessionId === 'string')
-}
-
 /**
- * Owned jobs are invisible to a caller-less `list`, so every attached session is asked for its own
+ * Owned jobs are invisible to a caller-less `list`, so every live session is asked for its own
  * bucket as well. One job can only be owned by one session, and the id map keeps the union exact.
  */
 function listJobs(services, owners = []) {
@@ -117,122 +109,298 @@ function listJobs(services, owners = []) {
   return [...seen.values()]
 }
 
+const RUNNING_JOB = new Set(['running', 'stopping'])
+
+/** The last turn number this agent has opened, when the loop exposes one. */
+function lastTurnOf(agent) {
+  const value = agent?.phase?.lastTurn
+  return Number.isSafeInteger(value) ? value : null
+}
+
 /**
- * The Harness half of the plugin: what is running now, how to stop it, how to put it back. Every
- * method answers `restored` / `skipped` rather than throwing, because one item that cannot be put
- * back must not stop the items behind it.
+ * The Harness half of the plugin: what is running now, how to stop it, how to put it back.
+ *
+ * Restore outcomes are explicit:
+ * - `restored`: mounted, and for an interrupted turn a visible continuation message was admitted
+ * - `skipped`: nothing to do, or the person already moved on; not a failure and not retried
+ * - `attention`: restored as far as allowed, but something cannot be put back (a killed job)
+ * - `failed`: this item may work on the next press, so it stays unmarked for retry
+ * Nothing here throws for one broken item: the press reports it and the rest proceeds.
  */
-export function createProbe(services, heartbeat) {
-  const graceMs = 1500
+export function createProbe(services, options = {}) {
+  const graceMs = Number.isFinite(options.graceMs) ? options.graceMs : 1500
+  const continueText = typeof options.continueText === 'string' && options.continueText.trim() !== ''
+    ? options.continueText
+    : '继续'
 
-  async function live() {
-    const attached = await attachedRows(services)
-    const views = await Promise.all(attached.map((row) => goalOf(services, row.sessionId)))
+  /** Everything this press can stop, read from the live registry only. */
+  function live() {
+    const agents = agentsOf(services)
     const sessions = []
     const goals = []
-    attached.forEach((row, index) => {
-      const running = row.running === true
-      const goal = views[index]
-      const active = goal !== undefined && goal.phase === 'active'
-      // A session is part of the work in two cases only: a turn is running, or a goal is armed and
-      // can start one. A session the person merely has open is a tab, not work.
-      if (running || active) sessions.push({ sessionId: row.sessionId, running })
-      if (active) goals.push({ sessionId: row.sessionId, goalId: goal.id, revision: goal.revision })
-    })
-    const jobs = listJobs(services, attached.map((row) => row.sessionId))
-      .filter((job) => job.status === 'running' || job.status === 'stopping')
-      .map((job) => ({ id: job.id, label: job.label ?? job.kind ?? '', owner: job.owner }))
-    return { sessions, goals, schedules: [], jobs, terminals: [] }
+    const jobs = []
+    if (agents === undefined) {
+      // The registry is unreadable: report no work rather than claiming a state the button cannot see.
+      return { sessions, goals, jobs, readable: false, source: 'none' }
+    }
+    const unowned = listJobs(services)
+    for (const job of unowned) if (RUNNING_JOB.has(job.status)) jobs.push({ id: job.id, owner: null, status: job.status })
+    for (const agent of agents) {
+      const goal = goalView(services, agent)
+      const owned = listJobs(services, [agent.id])
+      sessions.push({ sessionId: agent.id, running: agent.status === 'running', lastTurn: lastTurnOf(agent) })
+      // A disarmed goal is not work: it will not start a round, and pausing it would throw. Only an
+      // active, armed goal is something this press can stop and this restore can re-arm.
+      if (goal !== undefined && goal.phase === 'active' && goal.activation === 'armed') {
+        goals.push({ sessionId: agent.id, goalId: goal.id, revision: goal.revision })
+      }
+      for (const job of owned) if (RUNNING_JOB.has(job.status)) jobs.push({ id: job.id, owner: agent.id, status: job.status })
+    }
+    const unique = new Map()
+    for (const job of jobs) if (!unique.has(job.id)) unique.set(job.id, job)
+    return { sessions, goals, jobs: [...unique.values()], readable: true, source: 'live' }
   }
 
+  /**
+   * Stop the captured work: disarm goals first so no round is queued behind the press, then end
+   * the open turns, then kill the jobs. The returned goal entries carry the revision produced by
+   * `pause`, which is what a later `resume` must prove.
+   */
   async function stop(current, { graceMs: grace } = {}) {
     const controller = service(services, 'sessionController')
     const goals = service(services, 'goals')
     const jobs = service(services, 'jobs')
     const canceled = []
     const unknown = []
+    const pausedGoals = []
+    const goalErrors = []
+    const killedJobs = []
+    const jobErrors = []
 
-    for (const session of current.sessions ?? []) {
-      if (session.running !== true) continue
+    for (const goal of current.goals ?? []) {
+      const agent = agentOf(services, goal.sessionId)
+      if (agent === undefined) continue
       try {
-        controller?.cancel?.({ sessionId: session.sessionId })
-        canceled.push(session.sessionId)
+        const view = goals.pause(agent, { id: goal.goalId, revision: goal.revision })
+        pausedGoals.push({ sessionId: goal.sessionId, goalId: view?.id ?? goal.goalId, pausedRevision: view?.revision ?? goal.revision + 1 })
       } catch (error) {
-        unknown.push(`session ${session.sessionId}: ${String(error?.message ?? error).slice(0, 80)}`)
+        goalErrors.push(`goal ${goal.goalId}: ${String(error?.message ?? error).slice(0, 80)}`)
       }
     }
-    for (const goal of current.goals ?? []) {
+
+    // Every open turn is asked to stop before the wait, so the grace period measures one round trip.
+    const stopping = (current.sessions ?? []).filter((session) => session.running === true)
+    for (const session of stopping) {
       try {
-        await goals?.pause?.(goalAgent(goal.sessionId), { id: goal.goalId, revision: goal.revision })
+        await controller?.cancel?.({ sessionId: session.sessionId })
+        canceled.push(session.sessionId)
       } catch (error) {
-        unknown.push(`goal ${goal.goalId}: ${String(error?.message ?? error).slice(0, 80)}`)
+        unknown.push(`session ${session.sessionId}: ${String(error?.message ?? error).slice(0, 80)}`)
       }
     }
+
     for (const job of current.jobs ?? []) {
       try {
-        jobs?.kill?.(job.id, job.owner)
-      } catch {
-        try {
-          jobs?.kill?.(job.id)
-        } catch (error) {
-          unknown.push(`job ${job.id}: ${String(error?.message ?? error).slice(0, 80)}`)
-        }
+        if (job.owner === null || job.owner === undefined) jobs?.kill?.(job.id)
+        else jobs?.kill?.(job.id, job.owner)
+        killedJobs.push({ id: job.id, owner: job.owner ?? null })
+      } catch (error) {
+        jobErrors.push(`job ${job.id}: ${String(error?.message ?? error).slice(0, 80)}`)
       }
     }
 
     // A turn ends when its tools return: the press waits a bounded moment for that instead of
     // claiming a stop that has not happened yet.
     const deadline = Date.now() + (grace ?? graceMs)
-    let pending = current.sessions?.filter((session) => session.running === true).map((session) => session.sessionId) ?? []
+    let pending = stopping.map((session) => session.sessionId)
     while (pending.length > 0 && Date.now() < deadline) {
-      await new Promise((resolve) => setTimeout(resolve, 80))
-      const stillRunning = new Set(await listRunning(services).catch(() => []))
+      await new Promise((resolve) => setTimeout(resolve, 60))
+      const stillRunning = new Set(listRunning(services))
       pending = pending.filter((id) => stillRunning.has(id))
     }
     for (const id of pending) unknown.push(`session ${id}: still running`)
-    return { canceled, unknown }
+
+    // The turn counter is only readable once the turn is over: a running phase carries the turn it
+    // is in, not the last finished one. Recording it now is what lets a restore tell "the press
+    // stopped turn 4" from "the person ran turn 5 while paused".
+    const sessions = stopping.map((session) => {
+      const agent = agentOf(services, session.sessionId)
+      return { sessionId: session.sessionId, lastTurn: agent === undefined ? null : lastTurnOf(agent) }
+    })
+
+    return { canceled, unknown, pausedGoals, goalErrors, killedJobs, jobErrors, stillRunning: pending, sessions }
   }
 
-  async function rearm(sessionId) {
-    const goals = service(services, 'goals')
-    const goal = await goalOf(services, sessionId)
-    if (goal === undefined) return false
-    if (goal.phase === 'active' && goal.activation !== 'armed') {
-      goals?.resume?.(goalAgent(sessionId), { id: goal.id, revision: goal.revision })
-      return true
+  /** The continuation message: a real user message, so the session history shows why it moved. */
+  function continuation(plan, sessionId) {
+    return {
+      sessionId,
+      requestId: `${plan.planId}:continue:${sessionId}`,
+      content: [{ type: 'text', text: continueText }],
+      // `queue` is the shipped public mode: deliver after the current turn, start one when idle.
+      mode: 'queue',
     }
-    return false
   }
 
-  async function restoreSession(session) {
+  /** Mount one session through the public resume path, which restores preset and model selection. */
+  async function mount(sessionId) {
+    const controller = service(services, 'sessionController')
+    if (controller !== undefined && controller !== null && typeof controller.resolveAgent === 'function') {
+      const resolved = await controller.resolveAgent(sessionId)
+      // The shipped service returns the Agent itself when it is already live, `{ agent }` after a
+      // cold resume, and `{ error }` when the resume failed. All three are official shapes.
+      if (resolved !== null && typeof resolved === 'object' && 'error' in resolved) throw resolved.error
+      const agent = resolved !== null && typeof resolved === 'object' && 'agent' in resolved ? resolved.agent : resolved
+      if (agent === undefined || agent === null || typeof agent.id !== 'string') throw new Error('resume returned no agent')
+      return agent
+    }
     const agents = service(services, 'agents')
     if (agents === undefined || agents === null || typeof agents.resume !== 'function') throw new Error('agents unavailable')
-    if (agentOf(services, session.sessionId) !== undefined) return 'skipped'
-    await agents.resume({ resumeSessionId: session.sessionId })
-    await rearm(session.sessionId)
-    return 'restored'
+    await agents.resume({ resumeSessionId: sessionId })
+    const mounted = agentOf(services, sessionId)
+    if (mounted === undefined) throw new Error('session did not attach')
+    return mounted
   }
 
-  async function restoreGoal(goal) {
-    const goals = service(services, 'goals')
-    const view = await goalOf(services, goal.sessionId)
-    if (view === undefined || view.id !== goal.goalId) return 'skipped'
-    if (view.phase === 'active') return (await rearm(goal.sessionId)) ? 'restored' : 'skipped'
-    // The revision is the person's veto: a goal they changed by hand is not resurrected.
-    if (view.phase !== 'paused' || view.revision !== goal.revision) return 'skipped'
-    goals?.resume?.(goalAgent(goal.sessionId), { id: view.id, revision: view.revision })
-    return 'restored'
-  }
-
-  async function crashPlan() {
-    const captured = heartbeat.residue
-    if (captured === null) return null
-    const rows = await listSessions(services)
-    const existing = new Set(rows.map((row) => row.sessionId))
-    const sessions = captured.sessions.filter((row) => existing.has(row.sessionId)).map((row) => ({ sessionId: row.sessionId, running: true }))
+  /**
+   * Put one session back. A session whose turn was stopped by the press gets its continuation
+   * admitted; a session that only carried a goal is mounted and left to the goal driver.
+   */
+  async function restoreSession(session, { plan } = {}) {
+    if (session === null || typeof session?.sessionId !== 'string') return { status: 'skipped', detail: 'no session' }
+    const { sessionId } = session
+    let agent = agentOf(services, sessionId)
+    const mounted = agent !== undefined
+    if (agent === undefined) {
+      try {
+        agent = await mount(sessionId)
+      } catch (error) {
+        return { status: 'failed', detail: String(error?.message ?? error).slice(0, 120) }
+      }
+    }
+
+    if (session.running !== true) return { status: 'restored', detail: mounted ? 'mounted' : 'attached', continued: false }
+
+    // Someone continued by hand after the pause: the press must not add a second turn.
+    const baseline = Number.isSafeInteger(session.lastTurn) ? session.lastTurn : null
+    const turnBefore = lastTurnOf(agent)
+    if (agent.status === 'running' || (baseline !== null && turnBefore !== null && turnBefore > baseline)) {
+      return { status: 'skipped', detail: 'already continued', continued: false }
+    }
+
+    const controller = service(services, 'sessionController')
+    if (controller === undefined || controller === null || typeof controller.prompt !== 'function') {
+      return { status: 'failed', detail: 'prompt unavailable', continued: false }
+    }
+    const request = continuation(plan, sessionId)
+    try {
+      // Two arguments: the shipped service takes the caller's AbortSignal. Passing source metadata
+      // here made every restore fail on a live Harness while the fake in the tests accepted it.
+      await controller.prompt(request, new AbortController().signal)
+    } catch (error) {
+      return { status: 'failed', detail: String(error?.message ?? error).slice(0, 120), continued: false }
+    }
+
+    // Admission is not execution. The shipped prompt answers `{ accepted: true }` without waking a
+    // queue when the same request id was already admitted, so the press waits for the visible sign
+    // of a turn (running, or a newer lastTurn) before it calls this item restored.
+    const started = await waitForTurn(sessionId, baseline, options.settleMs)
+    if (started === true) return { status: 'restored', detail: mounted ? 'continued' : 'resumed and continued', continued: true }
+    return { status: 'attention', detail: 'continuation admitted, no turn started', continued: false }
+  }
+
+  /** Bounded poll for the visible sign that an admitted continuation actually opened a turn. */
+  async function waitForTurn(sessionId, baseline, settle) {
+    if (settle === 0) return false
+    const deadline = Date.now() + (Number.isFinite(settle) ? settle : 1200)
+    for (;;) {
+      const agent = agentOf(services, sessionId)
+      if (agent !== undefined) {
+        if (agent.status === 'running') return true
+        const turn = lastTurnOf(agent)
+        if (baseline !== null && turn !== null && turn > baseline) return true
+      }
+      if (Date.now() >= deadline) return false
+      await new Promise((resolve) => setTimeout(resolve, 60))
+    }
+  }
+
+  /** Re-arm one paused goal. The saved revision is the person's veto: a changed goal is not ours. */
+  async function restoreGoal(goal, { plan } = {}) {
+    if (goal === null || typeof goal?.sessionId !== 'string') return { status: 'skipped', detail: 'no goal' }
+    let agent = agentOf(services, goal.sessionId)
+    if (agent === undefined) {
+      try {
+        agent = await mount(goal.sessionId)
+      } catch (error) {
+        return { status: 'failed', detail: String(error?.message ?? error).slice(0, 120) }
+      }
+    }
+    const services_goals = service(services, 'goals')
+    if (services_goals === undefined || services_goals === null || typeof services_goals.resume !== 'function') {
+      return { status: 'failed', detail: 'goals unavailable' }
+    }
+    const view = goalView(services, agent)
+    if (view === undefined || (typeof goal.goalId === 'string' && view.id !== goal.goalId)) {
+      return { status: 'skipped', detail: 'goal is gone' }
+    }
+    // A goal that is already active and armed was restored by an earlier press, or re-armed by the
+    // person: it must not be touched again. A disarmed active goal is not ours to arm either.
+    if (view.phase === 'active') {
+      return view.activation === 'armed'
+        ? { status: 'skipped', detail: 'already active' }
+        : { status: 'skipped', detail: 'goal disarmed' }
+    }
+    if (view.phase !== 'paused') return { status: 'skipped', detail: `goal is ${view.phase}` }
+    // The saved revision is the person's veto: a goal edited after the pause is not ours to resume.
+    if (Number.isSafeInteger(goal.revision) && view.revision !== goal.revision) {
+      return { status: 'skipped', detail: 'goal changed' }
+    }
+    // The plan stores the revision observed after `pause`; 0.3 plans keep it in `revision`, 0.2
+    // plans called it `pausedRevision`.
+    const expected = Number.isSafeInteger(goal.revision) ? goal.revision : goal.pausedRevision
+    if (Number.isSafeInteger(expected) === false) return { status: 'attention', detail: 'goal has no saved revision' }
+    if (view.revision !== expected) return { status: 'skipped', detail: 'goal changed by hand' }
+    try {
+      services_goals.resume(agent, { id: view.id, revision: view.revision })
+    } catch (error) {
+      return { status: 'failed', detail: String(error?.message ?? error).slice(0, 120) }
+    }
+    return { status: 'restored', detail: 'armed' }
+  }
+
+  /**
+   * What a previous process left behind: sessions whose turn was open when that process ended.
+   * This process cannot know whether those turns finished, so it mounts them and says so. Only a
+   * press's own plan is allowed to continue a turn.
+   */
+  function crashPlan(residue, { planId } = {}) {
+    if (residue === null || residue === undefined) return null
+    const rows = Array.isArray(residue.sessions) ? residue.sessions : []
+    const sessions = rows
+      .filter((row) => typeof row?.sessionId === 'string')
+      .map((row) => ({ sessionId: row.sessionId, running: false, lastTurn: null, crash: true }))
     if (sessions.length === 0) return null
-    return { version: 1, status: 'paused', source: 'crash', sessions, goals: [], schedules: [], jobs: [], terminals: [] }
+    return {
+      version: 3, // ui-copy-ignore
+      planId: planId ?? `crash-${Date.now().toString(36)}`,
+      status: 'paused', // ui-copy-ignore
+      source: 'crash', // ui-copy-ignore
+      createdAt: new Date(Number.isFinite(residue.at) ? residue.at : Date.now()).toISOString(),
+      sessions,
+      goals: [], // ui-copy-ignore
+      jobs: [], // ui-copy-ignore
+      attention: [], // ui-copy-ignore
+      crashes: sessions.length, // ui-copy-ignore
+    }
   }
 
-  return { live, stop, restoreSession, restoreGoal, restoreSchedule: async () => 'skipped', crashPlan }
+  return {
+    live,
+    stop,
+    restoreSession,
+    restoreGoal,
+    restoreSchedule: async () => ({ status: 'skipped', detail: 'no schedules' }),
+    crashPlan,
+  }
 }