Skip to content

armgit / orca

Public Imported from GitHub
0

Orca is the place for working with a fleet of agents (e.g. Grok Bot, Claude Code). Run any coding agent with your own subscription. Available on desktop, mobile and remote runtime.

13.3 KB
Raw Blame
import { collectAgentTitleEvidence } from './agent-title-evidence'
import { PANE_AGENT_EVIDENCE_SOURCES } from './pane-agent-evidence-sources'
import type {
  PaneAgentEvidence,
  PaneAgentIdentity,
  PaneAgentIdentityInput,
  PaneAgentRunKey
} from './pane-agent-identity-resolver'
import type { PaneAgentEvidenceSource } from './pane-agent-evidence-sources'
import type { TerminalAgent } from './terminal-agent'
import type { TuiAgent } from './tui-agent'

/** All adapters delegate here so ranking, ambiguity and run eligibility cannot drift. */

/** Coverage requires authority-bearing evidence, independent of OS/remoteness; title alone never covers a pane. */
export type PaneAgentCoverage = 'covered' | 'uncovered'

/** Host proof uses an opaque PID+start-time incarnation, never just a process name. Missing/ambiguous start identity
 * means uncovered; raw platform tuples stay off the renderer/remote wire. */
export type ForegroundProcessProof = {
  agent: TerminalAgent
  /** Opaque host-derived PID+start-time token. Compared for equality only, never decoded. */
  processIncarnation: string
  ptyIncarnationId?: string
  /** The execution authority that stamped the proof (see agent-status-observation.ts). */
  authorityId: string
  /** Age on the AUTHORITY's clock at capture. Replicas decay from this plus `validForMs`,
   *  never by subtracting a host wall clock from a local `Date.now()`. */
  capturedAgeMs: number
  validForMs: number
}

/** Only positive process replacement permits incarnation advance. Sends, turns, titles, transport loss and renderer-only
 * foreground changes do not prove replacement. Contract for the rebind gate; not yet consumed by sequencers. */
export type PaneReplacementProof =
  | { kind: 'accepted-launch'; launchToken: string; ptyIncarnationId: string }
  | { kind: 'process-replacement'; processIncarnation: string; authorityId: string }
  | { kind: 'provider-session-attach'; providerSessionId: string }

/** Future capability-negotiated host evidence, bounded and JSON-safe; old peers ignore it. Never infer it from bare agentIdentity. */
export type PaneAgentIdentityEvidenceWire = {
  source: PaneAgentEvidenceSource
  coverage: PaneAgentCoverage
  authorityId?: string
  incarnation?: number
  freshness?: { capturedAgeMs: number; validForMs: number }
  /** Marks the scoped host-published title-only best-effort route (hand-started WSL panes).
   *  Counted separately, `unverifiable` for liveness, and never relabeled as covered proof. */
  titleOnlyActionFallback?: true
}

export type CanonicalPaneAgentIdentityInput = {
  hookAgent?: TerminalAgent | null
  hookIsLive?: boolean
  hookRun?: PaneAgentRunKey
  /** Separate live/completed rows where available; hookAgent with hookIsLive:false retains single-slot compatibility. */
  completedHookAgent?: TerminalAgent | null
  completedHookRun?: PaneAgentRunKey
  launchAgent?: TuiAgent | null
  launchRun?: PaneAgentRunKey
  /** Foreground names alone are weak hints; only fresh processProof qualifies as covered process evidence. */
  foregroundAgent?: TerminalAgent | null
  processProof?: ForegroundProcessProof | null
  sleepingSessionAgent?: TerminalAgent | null
  sleepingRun?: PaneAgentRunKey
  /** Tab-level display fallback only; ignored unless `allowSibling` opts in. */
  siblingAgent?: TerminalAgent | null
  /** Additional tab-level sibling observations retained for ambiguity checking. */
  siblingAgents?: readonly TerminalAgent[]
  allowSibling?: boolean
  title?: string | null
  currentRun?: PaneAgentRunKey
  minimumSource?: PaneAgentEvidenceSource
  /** Preserve the existing ladder while uncovered during migration; absent fallback uses title-only evidence, never a host-specific ranking. */
  uncoveredFallback?: { agent: TerminalAgent | null; titleOnly?: boolean }
}

export type CanonicalPaneAgentIdentity = {
  agent: TerminalAgent | null
  source: PaneAgentEvidenceSource | null
  coverage: PaneAgentCoverage
  /** True when the answer was derived from a parsed title (the uncovered/title-only marking). */
  titleOnly: boolean
  ambiguousAt?: PaneAgentEvidenceSource
  supersededSources: readonly PaneAgentEvidenceSource[]
}

/** Authority order, strongest first. This is the only place precedence is expressed. */
const SOURCE_RANK: readonly PaneAgentEvidenceSource[] = PANE_AGENT_EVIDENCE_SOURCES

/** Exported for the source/rank drift ratchet; the rank is the canonical source list itself. */
export const PANE_AGENT_SOURCE_RANK = SOURCE_RANK

/** Reject an unrecognised source instead of silently dropping it from the ranking loop. */
function sourceRankIndex(source: PaneAgentEvidenceSource): number {
  const index = SOURCE_RANK.indexOf(source)
  if (index === -1) {
    throw new Error(`Unknown pane-agent evidence source: ${String(source)}`)
  }
  return index
}

/** Run keys only supersede evidence from the same authority; unknown authorities stay eligible. */
function isPaneAgentRunEligible(
  run: PaneAgentRunKey | undefined,
  currentRun: PaneAgentRunKey | undefined
): boolean {
  return (
    run === undefined ||
    currentRun === undefined ||
    run.authorityId !== currentRun.authorityId ||
    run.incarnation === currentRun.incarnation
  )
}

/** Shared evidence ranking primitive used by every pane-identity adapter. */
export function resolveCanonicalPaneAgentEvidence<A extends string = TerminalAgent>(
  input: PaneAgentIdentityInput<A>
): PaneAgentIdentity<A> {
  const superseded: PaneAgentEvidenceSource[] = []
  const floor = input.minimumSource ? sourceRankIndex(input.minimumSource) : Number.MAX_SAFE_INTEGER
  const eligible = input.evidence.filter((item) => {
    if (item.source === 'sibling' && input.allowSibling !== true) {
      return false
    }
    if (sourceRankIndex(item.source) > floor) {
      return false
    }
    if (isPaneAgentRunEligible(item.run, input.currentRun)) {
      return true
    }
    superseded.push(item.source)
    return false
  })

  for (const source of SOURCE_RANK) {
    const matches = eligible.filter((item) => item.source === source)
    if (matches.length === 0) {
      continue
    }
    const agents = new Set(matches.map((item) => item.agent))
    if (agents.size > 1) {
      return { agent: null, source: null, ambiguousAt: source, supersededSources: superseded }
    }
    return { agent: matches[0].agent, source, supersededSources: superseded }
  }
  return { agent: null, source: null, supersededSources: superseded }
}

/** Freshness is judged on the authority's own clock: age at capture against its TTL. */
export function isForegroundProcessProofFresh(proof: ForegroundProcessProof): boolean {
  return (
    Number.isFinite(proof.capturedAgeMs) &&
    Number.isFinite(proof.validForMs) &&
    proof.capturedAgeMs >= 0 &&
    proof.validForMs > 0 &&
    proof.capturedAgeMs <= proof.validForMs
  )
}

/** A proof only carries identity for the agent it names; a name mismatch is no proof at all. */
function processEvidenceFromProof(
  input: CanonicalPaneAgentIdentityInput
): PaneAgentEvidence<TerminalAgent> | null {
  const proof = input.processProof
  if (!proof || !isForegroundProcessProofFresh(proof)) {
    return null
  }
  if (input.foregroundAgent && input.foregroundAgent !== proof.agent) {
    return null
  }
  return { source: 'process', agent: proof.agent }
}

export function resolveCanonicalPaneAgentIdentity(
  input: CanonicalPaneAgentIdentityInput
): CanonicalPaneAgentIdentity {
  const processEvidence = processEvidenceFromProof(input)
  // Coverage comes from authority-bearing sources that are still eligible for this run. A stale
  // hook/launch row can remain in the input after a pane is replaced; it must not make a title-only
  // answer look covered to a future action consumer.
  const covered = Boolean(
    (input.hookAgent && isPaneAgentRunEligible(input.hookRun, input.currentRun)) ||
    (input.completedHookAgent &&
      isPaneAgentRunEligible(input.completedHookRun, input.currentRun)) ||
    processEvidence ||
    (input.launchAgent && isPaneAgentRunEligible(input.launchRun, input.currentRun)) ||
    (input.sleepingSessionAgent && isPaneAgentRunEligible(input.sleepingRun, input.currentRun))
  )
  // Keep stale evidence in the resolver so diagnostics still report which source was superseded,
  // even when it no longer qualifies the pane as covered.
  const hasAuthorityEvidence = Boolean(
    input.hookAgent ||
    input.completedHookAgent ||
    processEvidence ||
    input.launchAgent ||
    input.sleepingSessionAgent
  )
  const titleEvidence = input.title ? collectAgentTitleEvidence(input.title) : null
  const titleAgent = titleEvidence?.agent ?? null

  if (!hasAuthorityEvidence) {
    if (input.uncoveredFallback) {
      const agent = input.uncoveredFallback.agent
      // A legacy title parser may have picked the first token from an ambiguous or
      // free-text-only title. Do not let that compatibility value bypass the canonical
      // ambiguity fence when the caller marks it as title-only evidence.
      const rejectTitleFallback =
        input.uncoveredFallback.titleOnly === true &&
        ((titleEvidence?.reason === 'free-text-only' &&
          (titleEvidence.freeTextNames?.length ?? 0) > 1) ||
          titleEvidence?.reason === 'conflicting-anchored-names' ||
          titleEvidence?.reason === 'conflicting-vendor-markers')
      if (rejectTitleFallback) {
        return {
          agent: null,
          source: null,
          coverage: 'uncovered',
          titleOnly: false,
          ...(titleEvidence?.reason === 'free-text-only' ? {} : { ambiguousAt: 'title' as const }),
          supersededSources: []
        }
      }
      const titleOnly =
        input.uncoveredFallback.titleOnly ?? (agent !== null && agent === titleAgent)
      return {
        agent,
        source: agent === null ? null : titleOnly ? 'title' : null,
        coverage: 'uncovered',
        titleOnly,
        supersededSources: []
      }
    }
    const siblingEvidence = [
      ...(input.siblingAgent ? [{ source: 'sibling' as const, agent: input.siblingAgent }] : []),
      ...(input.siblingAgents?.map((agent) => ({ source: 'sibling' as const, agent })) ?? []),
      ...(titleAgent ? [{ source: 'title' as const, agent: titleAgent }] : [])
    ]
    const siblingResolved = resolveCanonicalPaneAgentEvidence<TerminalAgent>({
      evidence: siblingEvidence,
      allowSibling: input.allowSibling,
      minimumSource: input.minimumSource
    })
    return {
      agent: siblingResolved.agent,
      source: siblingResolved.source,
      coverage: 'uncovered',
      titleOnly: siblingResolved.source === 'title',
      ...(siblingResolved.ambiguousAt ? { ambiguousAt: siblingResolved.ambiguousAt } : {}),
      supersededSources: siblingResolved.supersededSources
    }
  }

  const resolved = resolveCanonicalPaneAgentEvidence<TerminalAgent>({
    evidence: [
      ...(input.hookAgent
        ? [
            {
              source: input.hookIsLive ? ('live-hook' as const) : ('completed-hook' as const),
              agent: input.hookAgent,
              ...(input.hookRun ? { run: input.hookRun } : {})
            }
          ]
        : []),
      ...(input.completedHookAgent
        ? [
            {
              source: 'completed-hook' as const,
              agent: input.completedHookAgent,
              ...(input.completedHookRun ? { run: input.completedHookRun } : {})
            }
          ]
        : []),
      ...(processEvidence ? [processEvidence] : []),
      ...(input.launchAgent
        ? [
            {
              source: 'launch' as const,
              agent: input.launchAgent,
              ...(input.launchRun ? { run: input.launchRun } : {})
            }
          ]
        : []),
      ...(input.sleepingSessionAgent
        ? [
            {
              source: 'sleeping-session' as const,
              agent: input.sleepingSessionAgent,
              ...(input.sleepingRun ? { run: input.sleepingRun } : {})
            }
          ]
        : []),
      ...(input.siblingAgent ? [{ source: 'sibling' as const, agent: input.siblingAgent }] : []),
      ...(input.siblingAgents?.map((agent) => ({ source: 'sibling' as const, agent })) ?? []),
      ...(titleAgent ? [{ source: 'title' as const, agent: titleAgent }] : [])
    ],
    currentRun: input.currentRun,
    minimumSource: input.minimumSource,
    allowSibling: input.allowSibling
  })
  return {
    agent: resolved.agent,
    source: resolved.source,
    coverage: covered ? 'covered' : 'uncovered',
    titleOnly: resolved.source === 'title',
    ...(resolved.ambiguousAt ? { ambiguousAt: resolved.ambiguousAt } : {}),
    supersededSources: resolved.supersededSources
  }
}

/** Projects the host-local sidecar onto the optional wire shape. Returns undefined when there is
 *  nothing to publish — absence stays absence, and a bare `agentIdentity` with no sidecar is
 *  never treated as covered proof by any consumer. */
export function buildPaneAgentIdentityEvidenceWire(
  identity: CanonicalPaneAgentIdentity,
  run?: PaneAgentRunKey,
  freshness?: { capturedAgeMs: number; validForMs: number }
): PaneAgentIdentityEvidenceWire | undefined {
  if (identity.agent === null || identity.source === null) {
    return undefined
  }
  return {
    source: identity.source,
    coverage: identity.coverage,
    ...(run ? { authorityId: run.authorityId, incarnation: run.incarnation } : {}),
    ...(freshness ? { freshness } : {}),
    ...(identity.coverage === 'uncovered' && identity.titleOnly
      ? { titleOnlyActionFallback: true as const }
      : {})
  }
}