dsh-codex-style-computer-use 1.2.1 → 1.3.0

package/lib/cycle-lifecycle.js

@@ -0,0 +1,66 @@
+// Finishing desktop work releases the machine without cancelling the conversation.
+export function createCycleLifecycle ({ gate, cu, claimOf, owner, paused, inFlight, ownershipOf = () => null }) {
+  const refusal = reason => ({ released: false, reason, conversationContinues: true })
+  let pendingCompletion = null
+
+  async function release (exec, why = 'desktop work finished', automatic = false, expected) {
+    if (!gate.isLive()) return { released: false, alreadyReleased: true, conversationContinues: true }
+    const ownership = expected || ownershipOf(exec) || { claim: claimOf(exec), cycleId: gate.snapshot().id }
+    const { claim, cycleId } = ownership
+    gate.assertOwnership(claim, cycleId)
+    if (paused() || cu.exited || cu.cooperation?.active) return refusal('a manual pause, question, exit, or active human handoff still owns this cycle')
+    if (inFlight() > (automatic ? 0 : 1)) return refusal('computer-use calls are still in flight')
+    const token = gate.beginCompletion(claim, cycleId)
+    try {
+      const result = await cu.calm({ beforeDispatch: () => {
+        const current = gate.snapshot()
+        if (current.id !== token.cycleId || current.state !== 'releasing' || current.ownerIdent !== token.ident ||
+            current.exitVersion !== token.exitVersion) {
+          throw Object.assign(new Error('COMPUTER_OWNER_CHANGED: this cleanup no longer owns the releasing cycle; no cleanup was dispatched.'),
+            { code: 'COMPUTER_OWNER_CHANGED', outcome: 'not-dispatched' })
+        }
+      } })
+      if (result?.released === false || paused() || cu.exited) {
+        gate.cancelCompletion(token)
+        return refusal(result?.reason || 'a newer pause or exit superseded completion')
+      }
+      const released = gate.finishCompletion(token)
+      return { released, ...(released ? {} : { reason: 'a newer cycle state superseded completion' }),
+        conversationContinues: true, cycleEnded: released,
+        message: released ? 'Computer-use control and monitoring released. Continue the conversation normally; a later required desktop call may acquire a fresh cycle.' : 'The current cycle state remains authoritative.' }
+    } catch (error) {
+      gate.cancelCompletion(token)
+      throw error
+    }
+  }
+
+  function settle () {
+    if (!pendingCompletion || inFlight() !== 0) return null
+    const pending = pendingCompletion
+    try { gate.assertOwnership(pending.ownership.claim, pending.ownership.cycleId) }
+    catch { pendingCompletion = null; return null } // Old events cannot close a newer turn or cycle.
+    if (paused() || cu.exited) { pendingCompletion = null; return null }
+    if (cu.cooperation?.active) return null // Handback will drain this same captured completion.
+    pendingCompletion = null
+    return release(pending.exec, pending.why, true, pending.ownership)
+  }
+
+  function requestCompletion (exec, why) {
+    if (!exec?.agent || paused() || !gate.isLive() || gate.state() !== 'open') return null
+    pendingCompletion = { exec, why, ownership: { claim: claimOf(exec), cycleId: gate.snapshot().id } }
+    return settle()
+  }
+
+  function completeTurn (session, kind = 'completed') {
+    if (kind === 'aborted' || kind === 'interrupted' || !gate.ownsSession(claimOf({ session }).sessionKey)) return null
+    const exec = owner()
+    return requestCompletion(exec, `owner turn ${kind}`)
+  }
+
+  function idle (agent) {
+    if (!agent || !gate.ownsAgent(claimOf({ agent }).agentKey)) return null
+    return requestCompletion(owner(), 'owner finished desktop work')
+  }
+
+  return { release, completeTurn, idle, settle }
+}

package/lib/cycle.js

@@ -16,9 +16,10 @@
 //     cannot open a cycle at all. The attempt itself is ONE shared settled-once promise per
 //     qualification, so concurrent calls in a turn cannot slip an op into the worker's stdin ahead
 //     of the `resume` that opens the cycle (build/test-cycle-gate.mjs measures that ordering).
-//   * `ended` is terminal for that id. A new cycle needs a NEW qualification (a later turn's first
-//     real call) and gets a NEW id. Nothing about Ctrl+Alt+R, a mouse event or a late callback can
-//     revive an ended cycle.
+//   * `ended` is terminal for that id. A new cycle needs a NEW qualification and gets a NEW id.
+//     A later turn qualifies naturally; explicit successful owner completion can also requalify
+//     that owner in the same turn. Ctrl+Alt+Q stays terminal for its turn. Neither a mouse event
+//     nor a late callback can revive an ended cycle.
 //
 // NO MEMORY BOUND LIVES IN THIS FILE, AND THAT IS DELIBERATE (#5, 2026-09-13). A cap that evicts a
 // consumed qualification is not a memory policy, it is a RE-AUTHORIZATION channel: after 64
@@ -55,7 +56,7 @@ export function createCycleGate ({
 } = {}) {
   let nextId = 0
   let exitVersion = 0   // bumped by every `ended`: a pending open compares it before/after its await
-  /** @type {{id:number, ownerIdent:string|null, ownerLabel:string, ownerSessionKey:string|null, ownerAgentKey:string|null, state:'open'|'paused'|'asking'|'ended', openedAt:number, lastAt:number, endedWhy:string}|null} */
+  /** @type {{id:number, ownerIdent:string|null, ownerLabel:string, ownerSessionKey:string|null, ownerAgentKey:string|null, state:'open'|'paused'|'asking'|'releasing'|'ended', openedAt:number, lastAt:number, endedWhy:string}|null} */
   let cycle = null
   /** qualification PER IDENTITY: ident -> {turn, promise, dead}. One entry per identity, never evicted. */
   const idents = new Map()
@@ -64,18 +65,29 @@ export function createCycleGate ({
   /** ident -> the turn generation in which an exit was seen: that turn may not open a cycle */
   const endedTurns = new Map()
   const events = []   // bounded transition log for the guards and diagnostics
+  const objectIds = new WeakMap()
+  let nextObjectId = 0
+  const identityKey = (value, preferred, kind) => {
+    const key = preferred(value)
+    if (key) return String(key)
+    if (value && (typeof value === 'object' || typeof value === 'function')) {
+      if (!objectIds.has(value)) objectIds.set(value, `${kind}-object-${++nextObjectId}`)
+      return objectIds.get(value)
+    }
+    return null
+  }
 
   const note = (what, detail) => {
     events.push({ at: now(), what, ...(detail || {}) })
     if (events.length > 96) events.shift()
   }
 
-  const identOf = (sessionKeyVal, agentKeyVal) => `${sessionKeyVal || '-'}|${agentKeyVal || '-'}`
+  const identOf = (sessionKeyVal, agentKeyVal) => JSON.stringify([sessionKeyVal, agentKeyVal])
 
   /** A claim is what the CALL brings: whose call it is, and which of that session's turns it is in. */
   function claim ({ session, agent } = {}) {
-    const sk = sessionKey(session)
-    const ak = agentKey(agent)
+    const sk = identityKey(session, sessionKey, 'session')
+    const ak = identityKey(agent, agentKey, 'agent')
     const turn = (sk && turns.get(sk)) || 0
     const ident = identOf(sk, ak)
     return {
@@ -91,7 +103,7 @@ export function createCycleGate ({
 
   /** Renewed by THAT session's turn/start only. Another session's event must not touch it (B). */
   function noteTurnStart (session) {
-    const sk = sessionKey(session)
+    const sk = identityKey(session, sessionKey, 'session')
     if (!sk) return 0
     const n = (turns.get(sk) || 0) + 1
     turns.set(sk, n)
@@ -131,6 +143,13 @@ export function createCycleGate ({
    * not a warning — lib/tools.js rethrows it so the call fails loudly instead of driving anyway.
    */
   function open (cl, openFn) {
+    if (!cl.sessionKey && !cl.agentKey) {
+      const err = new Error('COMPUTER_OWNER_REQUIRED: computer-use requires a stable session or agent identity; no operation was dispatched.')
+      err.dshCycleRefusal = true
+      err.code = 'COMPUTER_OWNER_REQUIRED'
+      err.outcome = 'not-dispatched'
+      throw err
+    }
     // A live cycle with NO owner is a pause/ask that arrived before any call claimed the machine.
     // Ownership is free: the next real call adopts it. Only a cycle owned by a DIFFERENT session is
     // a refusal.
@@ -145,11 +164,16 @@ export function createCycleGate ({
       const err = new Error(
         `this machine is owned by another computer-use cycle (owner ${cycle.ownerLabel}, cycle ` +
         `#${cycle.id}, state ${cycle.state}) — a session that is not the owner must not drive it. ` +
-        'Ask the human to end that session (Ctrl+Alt+Q) or wait for its turn to finish, then retry.')
+        'Keep this task pending until the owner finishes or explicitly releases computer use, then retry.')
       err.dshCycleRefusal = true
       note('refused-foreign', { owner: cycle.ownerLabel, id: cycle.id, by: cl.label })
       throw err
     }
+    if (isLive(cycle) && (cycle.state === 'releasing' || cycle.terminating)) {
+      const err = new Error('COMPUTER_CYCLE_RELEASING: the owning agent is releasing computer use. Wait for release to finish before starting a fresh cycle.')
+      err.dshCycleRefusal = true; err.code = 'COMPUTER_CYCLE_RELEASING'; err.outcome = 'not-dispatched'
+      throw err
+    }
 
     // ONE qualification per (session, agent, turn), kept per identity and NEVER evicted.
     let e = idents.get(cl.ident)
@@ -278,6 +302,72 @@ export function createCycleGate ({
     claim,
     noteTurnStart,
     open,
+    // Recheck the original call's claim after every async wait. Re-deriving it
+    // would silently give an old tool the identity of a newer turn.
+    assertOwnership (cl, expectedCycleId) {
+      const currentTurn = (cl.sessionKey && turns.get(cl.sessionKey)) || 0
+      if (!isLive(cycle) || cycle.state === 'releasing' || cycle.terminating || !ownedBy(cycle, cl) || cycle.id !== expectedCycleId ||
+          cl.turn !== currentTurn || idents.get(cl.ident)?.dead) {
+        const err = new Error('COMPUTER_OWNER_CHANGED: this call no longer owns the active computer-use cycle. No further input was dispatched; only the current owner may continue.')
+        err.dshCycleRefusal = true
+        err.code = 'COMPUTER_OWNER_CHANGED'
+        err.outcome = 'not-dispatched'
+        throw err
+      }
+      return true
+    },
+    // Complete the machine cycle without ending the chat. The intermediate state
+    // closes the async gap while the native worker releases its lease.
+    beginCompletion (cl, expectedCycleId) {
+      this.assertOwnership(cl, expectedCycleId)
+      if (cycle.state !== 'open') {
+        const err = new Error('COMPUTER_CYCLE_PAUSED: a human pause or active question keeps computer-use ownership; resume it before voluntarily releasing the cycle.')
+        err.dshCycleRefusal = true; err.code = 'COMPUTER_CYCLE_PAUSED'; err.outcome = 'not-dispatched'
+        throw err
+      }
+      const token = { cycleId: cycle.id, ident: cl.ident, turn: cl.turn, exitVersion }
+      cycle.completion = token
+      cycle.state = 'releasing'
+      note('completion-started', { id: cycle.id, owner: cl.label })
+      return token
+    },
+    // Host cancellation/disposal ends this turn's right to input immediately,
+    // but holds ownership until native cleanup finishes. A manual pause keeps its
+    // latch; after R the deferred terminal cleanup runs without waking that task.
+    beginTermination (cl, expectedCycleId, why, hold = false) {
+      if (!isLive(cycle) || !ownedBy(cycle, cl) || cycle.id !== expectedCycleId) return null
+      cycle.terminating = true
+      rememberEndedTurn(cl)
+      if (hold || cycle.state === 'paused' || cycle.state === 'asking') return { deferred: true }
+      if (cycle.state === 'releasing' && cycle.completion) {
+        cycle.completion.terminal = true; cycle.completion.why = why
+        return { joined: true, token: cycle.completion }
+      }
+      const token = { cycleId: cycle.id, ident: cl.ident, turn: cl.turn, exitVersion, terminal: true, why }
+      cycle.completion = token; cycle.state = 'releasing'
+      note('termination-started', { id: cycle.id, owner: cl.label, why })
+      return { token }
+    },
+    finishCompletion (token) {
+      if (!cycle || cycle.completion !== token || cycle.state !== 'releasing' ||
+          cycle.id !== token.cycleId || exitVersion !== token.exitVersion) return false
+      cycle.state = 'ended'
+      cycle.endedWhy = token.terminal ? token.why : 'owner completed computer use; chat remains active'
+      cycle.lastAt = now()
+      cycle.completion = null
+      exitVersion++
+      const e = idents.get(token.ident)
+      if (!token.terminal && e && !e.dead && e.turn === token.turn) e.promise = null
+      note('completed', { id: cycle.id, owner: cycle.ownerLabel })
+      return true
+    },
+    cancelCompletion (token) {
+      if (!cycle || cycle.completion !== token || cycle.state !== 'releasing' ||
+          cycle.id !== token.cycleId || exitVersion !== token.exitVersion) return false
+      cycle.state = 'open'; cycle.completion = null
+      note('completion-failed', { id: cycle.id })
+      return true
+    },
     mark,
     forgetIdentity,
     snapshot: () => ({