PaperClipAI/server/src/modules/run-dispatch/domain/wake-context.ts

// Shared wake-reason and retry-reason constants, and the pure classifiers
// that read them off a run's context snapshot. `heartbeat.ts` and this
// module's own Postgres adapter both decide on the same context snapshot
// shape, so this file is their one shared source for it: a second,
// independently maintained copy in either file could silently drift out of
// sync with the other and change only one of the two gates that read it.

function parseObject(value: unknown): Record<string, unknown> {
  return typeof value === "object" && value !== null && !Array.isArray(value)
    ? (value as Record<string, unknown>)
    : {};
}

function readNonEmptyString(value: unknown): string | null {
  return typeof value === "string" && value.trim().length > 0 ? value : null;
}

export const MAX_TURN_CONTINUATION_RETRY_REASON = "max_turns_continuation";
export const WORKSPACE_BUSY_RETRY_REASON = "workspace_busy";
export const AI_CONNECTION_POOL_WAIT_RETRY_REASON = "ai_connection_pool_wait";
export const AI_CONNECTION_BUSY_RETRY_REASON = "ai_connection_busy";
export const RUNNER_REVISION_WAIT_RETRY_REASON = "runner_revision_wait";
export const INTERACTION_CONTINUATION_INFRA_RETRY_REASON = "interaction_continuation_infra_retry";
export const INTERACTION_CONTINUATION_INFRA_WAKE_REASON = "interaction_continuation_infra_retry";
export const WAKE_COMMENT_IDS_KEY = "wakeCommentIds";
export const RESOLVED_INTERACTION_CONTINUATION_STATUSES = new Set([
  "accepted",
  "answered",
  "cancelled",
  "rejected",
]);

// A run silent for this long no longer counts as the shared-workspace holder
// it was waiting behind. Kept here so the deferral gate and the parked-wait
// check in this module's adapter read one value.
export const WORKSPACE_BUSY_HOLDER_STALE_AFTER_MS = 60 * 60 * 1000;
// Fallback re-check for a parked workspace wait. The holder ending wakes the
// waiter directly; this only bounds a missed wake.
export const WORKSPACE_BUSY_PARKED_RECHECK_MS = 5 * 60 * 1000;
// Re-check for a wait behind an ended remote writer whose save or sandbox
// release has not settled. Settling has no single completion point to wake
// from, so the parked run re-checks on this cadence. Each check creates no run.
// It reads the workspace, the writer run, its task, and the writer's leases
// (one row per sandbox lease of that run, so a small set) in the promotion
// transaction. The checks last only while the wait exists, up to the cutoff.
export const WORKSPACE_BUSY_SETTLING_RECHECK_MS = 60 * 1000;
export const WORKSPACE_BUSY_WAIT_KEY = "workspaceBusyWait";

/** What a workspace-busy retry is waiting behind, recorded at deferral. */
export type WorkspaceBusyWait = {
  /** `execution:<id>` or `project:<id>`; waiters on one key are admitted in arrival order. */
  key: string;
  holderRunId: string;
  /** ISO time of the first deferral for this key; carried across re-deferrals. */
  waitingSince: string;
  /**
   * The task's workspace binding when it deferred. The wait applies only while
   * the binding is unchanged; a remote reservation can defer before it binds.
   */
  issueExecutionWorkspaceId: string | null;
  issueProjectWorkspaceId: string | null;
};

export function workspaceBusyWaitKey(input: {
  executionWorkspaceId: string | null;
  projectWorkspaceId: string | null;
}): string | null {
  if (input.executionWorkspaceId) return `execution:${input.executionWorkspaceId}`;
  if (input.projectWorkspaceId) return `project:${input.projectWorkspaceId}`;
  return null;
}

export function readWorkspaceBusyWait(
  retryReason: string | null | undefined,
  contextSnapshot: Record<string, unknown> | null | undefined,
): WorkspaceBusyWait | null {
  if (retryReason !== WORKSPACE_BUSY_RETRY_REASON) return null;
  const wait = parseObject(parseObject(contextSnapshot)[WORKSPACE_BUSY_WAIT_KEY]);
  const key = readNonEmptyString(wait.key);
  const holderRunId = readNonEmptyString(wait.holderRunId);
  const waitingSince = readNonEmptyString(wait.waitingSince);
  if (!key || !holderRunId || !waitingSince || Number.isNaN(Date.parse(waitingSince))) return null;
  if (!("issueExecutionWorkspaceId" in wait) || !("issueProjectWorkspaceId" in wait)) return null;
  return {
    key, holderRunId, waitingSince,
    issueExecutionWorkspaceId: readNonEmptyString(wait.issueExecutionWorkspaceId),
    issueProjectWorkspaceId: readNonEmptyString(wait.issueProjectWorkspaceId),
  };
}

/**
 * True for a resource-wait retry whose original run did not
 * execute under assignee-ship (a comment or review-participant wake). Such a
 * retry has an expected assignee mismatch, so the scheduled-retry gate and
 * the queued-run staleness check must not treat it as a reassignment.
 */
export function isNonAssigneeWorkspaceBusyRetry(
  retryReason: string | null | undefined,
  contextSnapshot: Record<string, unknown>,
): boolean {
  return (
    (retryReason === WORKSPACE_BUSY_RETRY_REASON &&
      contextSnapshot.workspaceBusyDeferredWhileAssignee === false) ||
    ((retryReason === AI_CONNECTION_BUSY_RETRY_REASON || retryReason === AI_CONNECTION_POOL_WAIT_RETRY_REASON) &&
      contextSnapshot.aiConnectionBusyDeferredWhileAssignee === false)
  );
}

export function extractWakeCommentIds(
  contextSnapshot: Record<string, unknown> | null | undefined,
): string[] {
  const raw = contextSnapshot?.[WAKE_COMMENT_IDS_KEY];
  if (!Array.isArray(raw)) return [];
  const out: string[] = [];
  for (const entry of raw) {
    const value = readNonEmptyString(entry);
    if (!value || out.includes(value)) continue;
    out.push(value);
  }
  return out;
}

export function deriveCommentId(
  contextSnapshot: Record<string, unknown> | null | undefined,
  payload?: Record<string, unknown> | null,
): string | null {
  const batchedCommentId = extractWakeCommentIds(contextSnapshot).at(-1);
  return (
    batchedCommentId ??
    readNonEmptyString(contextSnapshot?.wakeCommentId) ??
    readNonEmptyString(contextSnapshot?.commentId) ??
    readNonEmptyString(payload?.commentId) ??
    null
  );
}

/**
 * The external chat conversation a wake answers. Several conversations can
 * share one issue (for example GitHub review finding threads), but a reviewed
 * chat run can attest only one, so wakes for different conversations must
 * never share a batch.
 */
export const CHAT_CONVERSATION_ID_KEY = "chatConversationId";

export function readWakeChatConversationId(contextSnapshot: unknown): string | null {
  return readNonEmptyString(parseObject(contextSnapshot)[CHAT_CONVERSATION_ID_KEY]);
}

/** True when both wakes answer a chat conversation and they are different ones. */
export function wakeChatConversationsConflict(existing: unknown, incoming: unknown): boolean {
  const existingId = readWakeChatConversationId(existing);
  const incomingId = readWakeChatConversationId(incoming);
  return existingId !== null && incomingId !== null && existingId !== incomingId;
}

/**
 * `allowedWakeReasons` is the issue-tree-control module's own set of wake
 * reasons that excuse an interaction wake. This file stays free of service
 * imports, so the caller passes the set in rather than this function reading
 * it from the service directly.
 */
export function allowsIssueInteractionWake(
  contextSnapshot: Record<string, unknown> | null | undefined,
  allowedWakeReasons: ReadonlySet<string>,
): boolean {
  const wakeReason = readNonEmptyString(contextSnapshot?.wakeReason);
  if (!wakeReason || !allowedWakeReasons.has(wakeReason)) return false;
  return Boolean(deriveCommentId(contextSnapshot));
}

/**
 * Whether a wake may run while its issue still has unresolved blockers: a
 * verified comment interaction, or a stalled child or blocker
 * (`issue_blocker_stalled`, once per stall), which the assignee must be able
 * to re-delegate, escalate or block on while that dependency is stuck. The
 * caller verifies the stall against server state (`verifyBlockerStallWake`);
 * the wake reason string alone never qualifies. Pause holds are separate and
 * do not use this rule.
 */
export function allowsDependencyBlockedWake(
  contextSnapshot: Record<string, unknown> | null | undefined,
  interactionWakeReasons: ReadonlySet<string>,
  verifiedBlockerStall: boolean,
): boolean {
  return allowsIssueInteractionWake(contextSnapshot, interactionWakeReasons) || verifiedBlockerStall;
}

export function isResolvedInteractionContinuationWakeContext(contextSnapshot: unknown): boolean {
  const context = parseObject(contextSnapshot);
  const interactionId = readNonEmptyString(context.interactionId);
  const interactionStatus = readNonEmptyString(context.interactionStatus);
  if (!interactionId || !interactionStatus) return false;
  const retiredConnection = interactionStatus === "expired"
    && context.interactionKind === "connection_intent"
    && context.connectionIntentResolution === "existing_connection";
  if (!retiredConnection && !RESOLVED_INTERACTION_CONTINUATION_STATUSES.has(interactionStatus)) return false;

  const mutation = readNonEmptyString(context.mutation);
  const wakeReason = readNonEmptyString(context.wakeReason);
  const retryReason = readNonEmptyString(context.retryReason);
  return (
    (mutation === "interaction" && wakeReason === "issue_commented") ||
    (mutation === "interaction" && retryReason === RUNNER_REVISION_WAIT_RETRY_REASON) ||
    wakeReason === INTERACTION_CONTINUATION_INFRA_WAKE_REASON ||
    retryReason === INTERACTION_CONTINUATION_INFRA_RETRY_REASON
  );
}