Skip to content

The ultimate harness for coding agents and beyond. All your agents. All your machines. One command center. Start with code, then follow your curiosity and build across disciplines: CAD, circuits, robots, games and music.

8.7 KB
Raw Blame
// The session an unbound, live agent runs, found for "Change agent"'s handoff, and the wiring of the
// handoff provider's dependencies (cli.ts passes the real functions, specs pass fakes). Discovery is
// read-only: it never binds anything, and it answers only when the answer is certain — a Change agent
// must not guess whose conversation it hands over. Consumed by lib/agentHandoff.ts.
import { handoffSessionFact, HandoffError } from './handoffAuthority.js'
import { sessionStoreOf } from '../engines/sessionStoreContracts.js'
import type { AgentEngine } from '../engines/types.js'
import type { HandoffDeps } from './agentHandoff.js'
import { isSubagentTranscript } from './subagentTranscript.js'
import type { RecentRecap } from './recapReads.js'
import type { RegisteredSession } from './registry.js'
import type { RepairedSession } from './sessionRepair.js'
import type { TurnSource } from './sessionSearch/sessionTurns.js'
import { SQLITE_BACKED_ENGINES } from './sqliteRead.js'

export interface DiscoveryDeps {
  /** Engines whose process keeps no record of its session: the born, unique session of a process (sessionRepair
   *  findLiveSession). */
  findLiveSession(engine: AgentEngine, cwd: string, startedAtMs: number, opts: { bornOnly: true; pid: number; codexHome?: string }): Promise<RepairedSession | null>
  /** An engine whose process keeps a record of its session (its session store's `live.record`, Claude Code's): the
   *  session it names, or null. Never a scan of its store. */
  processSession(engine: AgentEngine, pid: number, cwd: string, startedAtMs: number): Promise<RepairedSession | null>
  /** The agent has a live pane (not a stopped copy). */
  isLive(agentId: string): boolean
  current?(agentId: string): RegisteredSession | null | undefined
  observed?(session: RegisteredSession, found: TurnSource | null): void
  /** Another agent, running or stopped, already holds this session. Must answer true when it cannot tell. */
  ownedByOther(sessionId: string, agentId: string): boolean
  isRecentlyDeleted(sessionId: string): boolean
}

/** Engines whose conversation is a database row: `findLiveSession` matches those on activity time, not birth. */
const DATABASE_ENGINES: ReadonlySet<string> = new Set(SQLITE_BACKED_ENGINES)

/**
 * `HandoffDeps.discoverSession`: the session a live, unbound, non-fork agent of a file engine runs, found by its
 * process (pid and start marker) — an engine that keeps a per-process record only through it, the others only a
 * session born to that process — or null. Null too when the session is a subagent's, was just deleted, or another agent holds it.
 * One search per agent at a time: a second request while one runs shares it.
 */
export function sessionDiscovery(deps: DiscoveryDeps): (session: RegisteredSession) => Promise<TurnSource | null> {
  const pending = new Map<string, Promise<TurnSource | null>>()

  async function find(session: RegisteredSession, cwd: string, pid: number, startedAt: number): Promise<TurnSource | null> {
    try {
      const live = sessionStoreOf(session.engine)?.live
      const found = live && 'record' in live
        ? await deps.processSession(session.engine, pid, cwd, startedAt)
        : await deps.findLiveSession(session.engine, cwd, startedAt, { bornOnly: true, pid, codexHome: session.codexHome ?? undefined })
      const current = deps.current?.(session.agentId)
      if (!deps.isLive(session.agentId) || deps.current && (!current || current.identityHold
        || handoffSessionFact(current).fingerprint !== handoffSessionFact(session).fingerprint)) throw new HandoffError('IDENTITY_UNAVAILABLE')
      if (!found) { deps.observed?.(session, null); return null }
      const path = found.transcriptPath
      if (!found.sessionId || !path || isSubagentTranscript(path)
        || deps.isRecentlyDeleted(found.sessionId) || deps.ownedByOther(found.sessionId, session.agentId)) throw new HandoffError('IDENTITY_UNAVAILABLE')
      const source = { engine: session.engine, sessionId: found.sessionId, transcriptPath: path }
      deps.observed?.(session, source)
      return source
    } catch { throw new HandoffError('IDENTITY_UNAVAILABLE') }
  }

  return (session) => {
    if (session.sessionId || !session.cwd || session.forkedFrom != null) return Promise.resolve(null)
    if (DATABASE_ENGINES.has(session.engine)) return Promise.resolve(null)
    // As the repair sweep: the process itself, by its start and pid. Without them there is nothing certain to look for.
    const pid = session.processIdentity?.pid
    const startedAt = Date.parse(session.processIdentity?.startMarker ?? '')
    if (typeof pid !== 'number' || !Number.isSafeInteger(pid) || pid <= 0 || !Number.isFinite(startedAt)) return Promise.resolve(null)
    let live = false
    try { live = deps.isLive(session.agentId) } catch { live = false }
    if (!live) return Promise.resolve(null)
    const key = handoffSessionFact(session).fingerprint
    const running = pending.get(key)
    if (running) return running
    const promise = find(structuredClone(session), session.cwd, pid, startedAt).finally(() => { if (pending.get(key) === promise) pending.delete(key) })
    pending.set(key, promise)
    return promise
  }
}

export interface OwnershipDeps {
  bySession(sessionId: string): { agentId: string } | null | undefined
  /** The ids of every stopped record on disk, readable or not. */
  stoppedIds(): string[]
  /** One stopped record; throws when it cannot be read. */
  stopped(agentId: string): { agentId: string; sessionId: string } | null
}

/**
 * Does an agent other than `agentId` hold `sessionId`, running or stopped? Fails closed, record by record: a
 * stopped record that cannot be read (or is unusable) might be the holder, so it counts as one. (The store's
 * `list()` skips such records silently, which would fail open.)
 */
export function ownedByOther(deps: OwnershipDeps, sessionId: string, agentId: string): boolean {
  try {
    const owner = deps.bySession(sessionId)
    if (owner && owner.agentId !== agentId) return true
    for (const id of deps.stoppedIds()) {
      if (id === agentId) continue
      const record = deps.stopped(id)
      if (!record || (record.sessionId === sessionId && record.agentId !== agentId)) return true
    }
    return false
  } catch { return true }
}

/** The real functions the provider is built from (cli.ts), so a spec can pass fakes and see each one reached. */
export interface HandoffWiring {
  publish?: HandoffDeps['publish']
  observed?: DiscoveryDeps['observed']
  registry: {
    resolve(id: string): RegisteredSession | null | undefined
    byAgent(id: string): unknown
    bySession(sessionId: string): { agentId: string } | null | undefined
  }
  stopped: { get(id: string): RegisteredSession | null; ids(): string[] }
  /** The recaps, as the core reads them back (core/turns/recaps.ts). */
  mirror: {
    recentAsks(sessionId: string, n?: number): string[]
    lastFullText(sessionId: string): string | undefined
    recent(sessionId: string, n?: number): RecentRecap[]
  }
  databaseHistory: HandoffDeps['readHistory']
  findLiveSession: DiscoveryDeps['findLiveSession']
  processSession: DiscoveryDeps['processSession']
  isRecentlyDeleted(sessionId: string): boolean
  findResumedTranscript: NonNullable<HandoffDeps['findTranscript']>
  validTranscriptPath(engine: AgentEngine, path: string, codexHome?: string): boolean
}

/**
 * The dependencies of `prepareAgentHandoff`. Call it ONCE: the discovery made here holds the one-search-per-agent
 * state, which must outlive any single request.
 */
export function handoffProviderDeps(w: HandoffWiring): HandoffDeps {
  return {
    publish: w.publish,
    resolve: (id) => w.registry.resolve(id) ?? w.stopped.get(id),
    readHistory: w.databaseHistory,
    recentAsks: (sid, n) => w.mirror.recentAsks(sid, n),
    lastFullText: (sid) => w.mirror.lastFullText(sid),
    recaps: (sid, n) => w.mirror.recent(sid, n).filter((e) => e.kind === 'summary').map((e) => e.recap || e.text).filter(Boolean),
    // A pane that has not found its session yet (a repair still pending): the session it runs, only when it is
    // certain. Never a fork, never a database engine, never one another agent holds.
    discoverSession: sessionDiscovery({
      observed: w.observed,
      findLiveSession: w.findLiveSession,
      processSession: w.processSession,
      isLive: (id) => !!w.registry.byAgent(id),
      current: (id) => w.registry.resolve(id),
      ownedByOther: (sid, id) => ownedByOther({
        bySession: (s) => w.registry.bySession(s), stoppedIds: () => w.stopped.ids(), stopped: (s) => w.stopped.get(s),
      }, sid, id),
      isRecentlyDeleted: (sid) => w.isRecentlyDeleted(sid),
    }),
    findTranscript: (engine, sid, opts) => w.findResumedTranscript(engine, sid, opts),
    transcriptOk: (engine, path, home) => w.validTranscriptPath(engine, path, home ?? undefined),
  }
}