@open-mercato/tillio 0.7.1-develop.7176.1.d229567a50

package/src/modules/tillio/lib/preset.ts

@@ -0,0 +1,226 @@
+import { parseBooleanToken } from '@open-mercato/shared/lib/boolean'
+import { createLogger } from '@open-mercato/shared/lib/logger'
+import type { IntegrationScope } from '@open-mercato/shared/modules/integrations/types'
+import { TILLIO_INTEGRATION_ID } from '../integration'
+import { environmentSchema, type TillioEnvironment } from './environment'
+import { attachOperator, detachOperator, TillioOperatorLimitError } from './operators'
+import type { TillioLockRunner } from './locking'
+import { readOperatorsBlob, type TillioCredentialsService, type TillioOperatorRecord } from './operators-store'
+
+const logger = createLogger('tillio').child({ component: 'preset' })
+
+export const TILLIO_ENV_VARS = {
+  apiUrl: 'OM_INTEGRATION_TILLIO_API_URL',
+  apiKey: 'OM_INTEGRATION_TILLIO_API_KEY',
+  timeZone: 'OM_INTEGRATION_TILLIO_TIMEZONE',
+  ringostatKey: 'OM_INTEGRATION_TILLIO_RINGOSTAT_KEY',
+  force: 'OM_INTEGRATION_TILLIO_FORCE_PRECONFIGURE',
+  replaceOperator: 'OM_INTEGRATION_TILLIO_REPLACE_OPERATOR',
+} as const
+
+export type TillioEnvPreset =
+  | { status: 'absent' }
+  | { status: 'incomplete'; missing: string[] }
+  | {
+    status: 'ready'
+    credentials: TillioEnvironment
+    ringostatKey: string | null
+    force: boolean
+    replaceOperator: boolean
+  }
+
+export type TillioPresetOutcome =
+  | { status: 'skipped'; reason: string }
+  | { status: 'blocked'; reason: string }
+  | {
+    status: 'applied'
+    credentialsAction: 'saved' | 'kept'
+    health: string
+    operator: 'attached' | 'kept' | 'not-requested' | 'failed'
+  }
+
+type IntegrationStateServiceLike = {
+  upsert: (
+    integrationId: string,
+    input: { isEnabled?: boolean },
+    scope: IntegrationScope,
+  ) => Promise<unknown>
+}
+
+type IntegrationHealthServiceLike = {
+  runHealthCheck: (integrationId: string, scope: IntegrationScope) => Promise<{ status: string; message?: string }>
+}
+
+type IntegrationLogServiceLike = {
+  scoped: (
+    integrationId: string,
+    scope: IntegrationScope,
+  ) => {
+    info: (message: string, fields?: Record<string, unknown>) => Promise<unknown>
+    warn: (message: string, fields?: Record<string, unknown>) => Promise<unknown>
+  }
+}
+
+export type ApplyTillioEnvPresetParams = {
+  credentialsService: TillioCredentialsService
+  integrationStateService: IntegrationStateServiceLike
+  integrationHealthService: IntegrationHealthServiceLike
+  scope: IntegrationScope
+  force?: boolean
+  env?: NodeJS.ProcessEnv
+  appUrl?: string
+  integrationLogService?: IntegrationLogServiceLike
+  // Supplied by the CLI, where somebody is at the terminal to answer. Tenant bootstrap passes
+  // nothing, so the swap is refused unless the deployment declared it through the env var.
+  confirmOperatorReplacement?: (operator: TillioOperatorRecord) => Promise<boolean>
+  /**
+   * Serializes the operator write against a concurrent attach from the admin UI. Optional
+   * because a bootstrap that runs before the app serves traffic has nothing to contend with;
+   * both shipped callers pass a real one.
+   */
+  withLock?: TillioLockRunner
+}
+
+function readValue(env: NodeJS.ProcessEnv, key: string): string | undefined {
+  const value = env[key]?.trim()
+  return value ? value : undefined
+}
+
+export function readTillioEnvPreset(env: NodeJS.ProcessEnv = process.env): TillioEnvPreset {
+  const apiUrl = readValue(env, TILLIO_ENV_VARS.apiUrl)
+  const apiKey = readValue(env, TILLIO_ENV_VARS.apiKey)
+  if (!apiUrl && !apiKey) return { status: 'absent' }
+
+  const missing: string[] = []
+  if (!apiUrl) missing.push(TILLIO_ENV_VARS.apiUrl)
+  if (!apiKey) missing.push(TILLIO_ENV_VARS.apiKey)
+  // Reported rather than thrown: a half-set preset must not take tenant bootstrap down with it.
+  if (missing.length) return { status: 'incomplete', missing }
+
+  return {
+    status: 'ready',
+    credentials: environmentSchema.parse({ apiUrl, apiKey, timeZone: readValue(env, TILLIO_ENV_VARS.timeZone) }),
+    ringostatKey: readValue(env, TILLIO_ENV_VARS.ringostatKey) ?? null,
+    force: parseBooleanToken(readValue(env, TILLIO_ENV_VARS.force)) ?? false,
+    replaceOperator: parseBooleanToken(readValue(env, TILLIO_ENV_VARS.replaceOperator)) ?? false,
+  }
+}
+
+function pointsAtAnotherEnvironment(
+  stored: Record<string, unknown> | null,
+  next: TillioEnvironment,
+): boolean {
+  const parsed = environmentSchema.safeParse(stored ?? {})
+  if (!parsed.success) return false
+  return parsed.data.apiUrl !== next.apiUrl || parsed.data.apiKey !== next.apiKey
+}
+
+async function attachOperatorFromPreset(params: {
+  credentialsService: TillioCredentialsService
+  scope: IntegrationScope
+  appUrl: string
+  ringostatKey: string
+  withLock: TillioLockRunner
+}): Promise<'attached' | 'kept' | 'failed'> {
+  if (!params.appUrl.trim()) {
+    logger.warn('cannot attach the operator without APP_URL')
+    return 'failed'
+  }
+
+  try {
+    await attachOperator(
+      {
+        credentialsService: params.credentialsService,
+        scope: params.scope,
+        appUrl: params.appUrl,
+        withLock: params.withLock,
+      },
+      { plugin: 'Ringostat', config: { key: params.ringostatKey } },
+    )
+    return 'attached'
+  } catch (err) {
+    // The slot is taken, which is the expected outcome of a rerun.
+    if (err instanceof TillioOperatorLimitError) return 'kept'
+    logger.warn('failed to attach the operator from the env preset', { err })
+    return 'failed'
+  }
+}
+
+// Every step goes through the service the admin UI uses for the same action, so an env-driven
+// bootstrap and a hand-configured one converge on identical stored state, and anything the preset
+// wrote stays editable in the UI afterwards.
+export async function applyTillioEnvPreset(params: ApplyTillioEnvPresetParams): Promise<TillioPresetOutcome> {
+  const preset = readTillioEnvPreset(params.env)
+
+  if (preset.status === 'absent') {
+    return { status: 'skipped', reason: 'No Tillio preset environment variables were provided.' }
+  }
+  if (preset.status === 'incomplete') {
+    const reason = `Incomplete Tillio env preset; missing ${preset.missing.join(', ')}.`
+    await params.integrationLogService?.scoped(TILLIO_INTEGRATION_ID, params.scope).warn(reason).catch(() => undefined)
+    return { status: 'skipped', reason }
+  }
+
+  const force = params.force ?? preset.force
+  const existing = await params.credentialsService.getRaw(TILLIO_INTEGRATION_ID, params.scope)
+  // Overwriting silently would undo a rotation somebody performed in the UI.
+  const credentialsAction = existing && !force ? 'kept' : 'saved'
+
+  if (credentialsAction === 'saved' && pointsAtAnotherEnvironment(existing, preset.credentials)) {
+    const attached = (await readOperatorsBlob(params.credentialsService, params.scope)).operators[0] ?? null
+    if (attached) {
+      if (!preset.ringostatKey) {
+        return {
+          status: 'blocked',
+          reason: `The attached operator belongs to the current environment. Set ${TILLIO_ENV_VARS.ringostatKey} so it can be reattached to the new one.`,
+        }
+      }
+
+      const approved = preset.replaceOperator
+        || (params.confirmOperatorReplacement ? await params.confirmOperatorReplacement(attached) : false)
+      if (!approved) {
+        return {
+          status: 'blocked',
+          reason: `Switching environments would strand the attached operator. Confirm the replacement or set ${TILLIO_ENV_VARS.replaceOperator}.`,
+        }
+      }
+
+      // Revoked while the credentials that minted its token are still stored; afterwards the new
+      // environment would reject the token and the record could only be dropped by force.
+      await detachOperator({ credentialsService: params.credentialsService, scope: params.scope }, attached.id)
+    }
+  }
+
+  if (credentialsAction === 'saved') {
+    await params.credentialsService.save(TILLIO_INTEGRATION_ID, { ...preset.credentials }, params.scope)
+  }
+
+  await params.integrationStateService.upsert(TILLIO_INTEGRATION_ID, { isEnabled: true }, params.scope)
+
+  // Also mints the tenant identity the operator token is bound to, so it has to run before attaching.
+  const health = await params.integrationHealthService.runHealthCheck(TILLIO_INTEGRATION_ID, params.scope)
+
+  let operator: 'attached' | 'kept' | 'not-requested' | 'failed' = 'not-requested'
+  if (preset.ringostatKey) {
+    operator = health.status === 'healthy'
+      ? await attachOperatorFromPreset({
+        credentialsService: params.credentialsService,
+        scope: params.scope,
+        appUrl: params.appUrl ?? process.env.APP_URL ?? '',
+        ringostatKey: preset.ringostatKey,
+        withLock: params.withLock ?? ((run) => run()),
+      })
+      : 'failed'
+  }
+
+  await params.integrationLogService
+    ?.scoped(TILLIO_INTEGRATION_ID, params.scope)
+    .info('Tillio was preconfigured from environment variables.', {
+      credentialsAction,
+      health: health.status,
+      operator,
+    })
+    .catch(() => undefined)
+
+  return { status: 'applied', credentialsAction, health: health.status, operator }
+}

package/src/modules/tillio/lib/pull-job.ts

@@ -0,0 +1,390 @@
+import type { AwilixContainer } from 'awilix'
+import type { EntityManager } from '@mikro-orm/postgresql'
+import type { CommandBus, CommandRuntimeContext } from '@open-mercato/shared/lib/commands'
+import { createLogger } from '@open-mercato/shared/lib/logger'
+import type { IntegrationScope } from '@open-mercato/shared/modules/integrations/types'
+import type {
+  NormalizedPhoneCall,
+  NormalizedPhoneCallBatch,
+  PhoneCallBatchAnomaly,
+} from '@open-mercato/shared/modules/phone_calls/types'
+import type { PhoneCallProviderAdapter } from '@open-mercato/shared/modules/phone_calls/provider'
+import type {
+  ProgressService,
+  ProgressServiceContext,
+} from '@open-mercato/core/modules/progress/lib/progressService'
+import {
+  PHONE_CALLS_CALL_INGEST_COMMAND_ID,
+  type IngestPhoneCallResult,
+} from '@open-mercato/core/modules/phone_calls/commands/calls'
+import { emitPhoneCallsEvent } from '@open-mercato/core/modules/phone_calls/events'
+import { TILLIO_INTEGRATION_ID, TILLIO_PROVIDER_KEY } from '../integration'
+import { tillioAdapter } from './adapter'
+import { TillioApiError } from './errors'
+import {
+  classifyTillioError,
+  readTillioIntegrationState,
+  resolveEnvironment,
+  type TillioResolvedEnvironment,
+} from './operators'
+import {
+  readOperatorsBlob,
+  type TillioCredentialsService,
+  type TillioOperatorRecord,
+} from './operators-store'
+import { evaluatePullReadiness, PULL_BLOCKER_MESSAGES, type PullReadiness } from './pull-readiness'
+import { zonedDayEnd, zonedDayStart } from './tz'
+
+const logger = createLogger('tillio').child({ component: 'pull-job' })
+
+export const TILLIO_PULL_JOB_TYPE = 'tillio.calls.pull'
+
+// Only trips when the provider keeps advertising further pages, which would spin forever.
+const MAX_BATCHES = 200
+
+export type TillioPullScope = {
+  tenantId: string
+  organizationId: string
+  userId?: string | null
+}
+
+// No operator token and no API key in the payload: the worker resolves credentials on every
+// attempt, so a job replayed after a rotation uses the current ones instead of stale copies.
+export type TillioPullJobPayload = {
+  progressJobId: string
+  scope: TillioPullScope
+  from: string
+  to: string
+  cursor?: string | null
+  limit?: number | null
+}
+
+export type TillioPullSummary = {
+  fetched: number
+  created: number
+  updated: number
+  failed: number
+  batches: number
+  cancelled: boolean
+  /** True when the sweep stopped before the range was exhausted. */
+  truncated: boolean
+  /** Where a follow-up pull should pick up. Null unless `truncated`. */
+  resumeCursor: string | null
+}
+
+export type TillioPullContext = {
+  readiness: PullReadiness
+  environment: TillioResolvedEnvironment | null
+  operator: TillioOperatorRecord | null
+}
+
+type IngestDeps = {
+  commandBus: CommandBus
+  commandContext: CommandRuntimeContext
+  scope: IntegrationScope
+}
+
+type BatchCounts = Pick<TillioPullSummary, 'created' | 'updated' | 'failed'>
+
+export async function resolvePullContext(
+  credentialsService: TillioCredentialsService,
+  em: EntityManager,
+  scope: IntegrationScope,
+): Promise<TillioPullContext> {
+  const environment = await resolveEnvironment(credentialsService, scope)
+  const integrationState = await readTillioIntegrationState(em, scope)
+  const blob = await readOperatorsBlob(credentialsService, scope)
+  const operator =
+    blob.operators.find((entry) => entry.id === blob.defaultOperatorId) ?? blob.operators[0] ?? null
+
+  return {
+    readiness: evaluatePullReadiness({
+      environment,
+      integrationEnabled: integrationState.enabled,
+      environmentHealthy: integrationState.healthy,
+      operator,
+    }),
+    environment,
+    operator,
+  }
+}
+
+function buildIngestInput(call: NormalizedPhoneCall, scope: IntegrationScope): Record<string, unknown> {
+  return {
+    organizationId: scope.organizationId,
+    tenantId: scope.tenantId,
+    providerKey: TILLIO_PROVIDER_KEY,
+    integrationId: TILLIO_INTEGRATION_ID,
+    externalCallId: call.externalCallId,
+    externalConversationId: call.externalConversationId ?? null,
+    direction: call.direction,
+    status: call.status,
+    participants: call.participants,
+    recording: call.recording ?? null,
+    startedAt: call.startedAt ?? null,
+    answeredAt: call.answeredAt ?? null,
+    endedAt: call.endedAt ?? null,
+    durationSeconds: call.durationSeconds ?? null,
+    providerFacts: call.providerFacts,
+    rawPayload: call.rawPayload,
+  }
+}
+
+// The initiating user travels in the job payload, so ingest writes carry an actor instead of
+// landing in the audit trail unattributed. The id was resolved from the session that queued
+// the pull, never from request input.
+function buildCommandContext(
+  container: AwilixContainer,
+  scope: IntegrationScope,
+  userId: string | null,
+): CommandRuntimeContext {
+  return {
+    container,
+    auth: userId
+      ? { sub: userId, tenantId: scope.tenantId, orgId: scope.organizationId, isSuperAdmin: false }
+      : null,
+    organizationScope: {
+      selectedId: scope.organizationId,
+      filterIds: [scope.organizationId],
+      allowedIds: [scope.organizationId],
+      tenantId: scope.tenantId,
+    },
+    selectedOrganizationId: scope.organizationId,
+    organizationIds: [scope.organizationId],
+  }
+}
+
+async function ingestBatch(calls: NormalizedPhoneCall[], deps: IngestDeps): Promise<BatchCounts> {
+  const counts: BatchCounts = { created: 0, updated: 0, failed: 0 }
+
+  for (const call of calls) {
+    try {
+      const executed = await deps.commandBus.execute<Record<string, unknown>, IngestPhoneCallResult>(
+        PHONE_CALLS_CALL_INGEST_COMMAND_ID,
+        { input: buildIngestInput(call, deps.scope), ctx: deps.commandContext },
+      )
+      if (executed.result.created) counts.created += 1
+      else counts.updated += 1
+    } catch (err) {
+      // One transaction per call, so a single bad record only bumps `failed` and the rest of
+      // the batch still lands.
+      counts.failed += 1
+      logger.warn('ingest failed for a pulled call', { externalCallId: call.externalCallId, err })
+      await emitPhoneCallsEvent('phone_calls.call.ingest_failed', {
+        providerKey: TILLIO_PROVIDER_KEY,
+        externalCallId: call.externalCallId,
+        organizationId: deps.scope.organizationId,
+        tenantId: deps.scope.tenantId,
+      }).catch(() => undefined)
+    }
+  }
+
+  return counts
+}
+
+type PullFailure = { code: string; message: string }
+
+// The progress bar renders `errorMessage` verbatim and has no path to a translated string, so
+// what goes in has to be ours: a provider message could carry Tillio's own wording, an internal
+// hostname or a token fragment. The raw error stays in the log, the stable code in the summary.
+function describeFailure(err: unknown): PullFailure {
+  if (err instanceof TillioApiError) {
+    return classifyTillioError(err) === 'environment'
+      ? { code: 'provider_unreachable', message: 'Tillio could not be reached or rejected the stored credentials.' }
+      : { code: 'provider_error', message: 'Tillio rejected the request for calls.' }
+  }
+  return { code: 'pull_failed', message: 'The Tillio pull could not be completed.' }
+}
+
+function describeTruncation(summary: TillioPullSummary, anomaly: PhoneCallBatchAnomaly | null): PullFailure {
+  if (anomaly) {
+    return {
+      code: 'pull_pagination_anomaly',
+      message: `Tillio returned an inconsistent page listing, so the sweep stopped early after ${summary.fetched} calls.`,
+    }
+  }
+  return {
+    code: 'pull_truncated',
+    message: `Stopped after ${summary.batches} batches with more calls left in the range; ${summary.fetched} calls were ingested.`,
+  }
+}
+
+// Safe to retry: the ingest command keys on (providerKey, externalCallId) and updates in place,
+// so a job the queue replays after a crash repeats work instead of duplicating rows.
+export async function runTillioPullJob(params: {
+  container: AwilixContainer
+  payload: TillioPullJobPayload
+  adapter?: PhoneCallProviderAdapter
+}): Promise<TillioPullSummary> {
+  const { container, payload } = params
+  const adapter = params.adapter ?? tillioAdapter
+  const scope: IntegrationScope = {
+    organizationId: payload.scope.organizationId,
+    tenantId: payload.scope.tenantId,
+  }
+
+  const progressService = container.resolve('progressService') as ProgressService
+  const progressContext: ProgressServiceContext = {
+    tenantId: payload.scope.tenantId,
+    organizationId: payload.scope.organizationId,
+    userId: payload.scope.userId ?? null,
+  }
+  const summary: TillioPullSummary = {
+    fetched: 0,
+    created: 0,
+    updated: 0,
+    failed: 0,
+    batches: 0,
+    cancelled: false,
+    truncated: false,
+    resumeCursor: null,
+  }
+
+  await progressService.startJob(payload.progressJobId, progressContext)
+
+  try {
+    const credentialsService = container.resolve('integrationCredentialsService') as TillioCredentialsService
+    const em = container.resolve('em') as EntityManager
+
+    // Not trusted from enqueue time: credentials can rotate or the operator can be detached
+    // while the job waits in the queue.
+    const { readiness, environment, operator } = await resolvePullContext(credentialsService, em, scope)
+    if (readiness.blocker || !environment || !operator) {
+      const blocker = readiness.blocker ?? 'environment_not_ready'
+      await progressService.failJob(
+        payload.progressJobId,
+        {
+          errorMessage: PULL_BLOCKER_MESSAGES[blocker],
+          resultSummary: { ...summary, code: blocker },
+        },
+        progressContext,
+      )
+      return summary
+    }
+
+    const deps: IngestDeps = {
+      commandBus: container.resolve('commandBus') as CommandBus,
+      commandContext: buildCommandContext(container, scope, payload.scope.userId ?? null),
+      scope,
+    }
+    const credentials = {
+      apiUrl: environment.apiUrl,
+      apiKey: environment.apiKey,
+      tenantSystemId: environment.tenantSystemId,
+      timeZone: environment.timeZone,
+      operator: {
+        id: operator.id,
+        plugin: operator.plugin,
+        token: operator.token,
+        tenantDomain: operator.tenantDomain,
+      },
+    }
+    const fetchBatch = (cursor: string | null): Promise<NormalizedPhoneCallBatch> =>
+      adapter.fetchCalls({
+        credentials,
+        scope,
+        integrationId: TILLIO_INTEGRATION_ID,
+        from: zonedDayStart(payload.from, environment.timeZone),
+        to: zonedDayEnd(payload.to, environment.timeZone),
+        cursor,
+        limit: payload.limit ?? null,
+      })
+
+    let cursor = payload.cursor ?? null
+    let anomaly: PhoneCallBatchAnomaly | null = null
+
+    while (summary.batches < MAX_BATCHES) {
+      const cancelled = await progressService.isCancellationRequested(
+        payload.progressJobId,
+        payload.scope.tenantId,
+        payload.scope.organizationId,
+      )
+      if (cancelled) {
+        summary.cancelled = true
+        await progressService.markCancelled(payload.progressJobId, progressContext)
+        return summary
+      }
+
+      const batch = await fetchBatch(cursor)
+      const counts = await ingestBatch(batch.calls, deps)
+
+      summary.batches += 1
+      summary.fetched += batch.calls.length
+      summary.created += counts.created
+      summary.updated += counts.updated
+      summary.failed += counts.failed
+
+      // Tillio reports no range total, so the job carries a processed count without a total
+      // and the top bar renders it without a percentage.
+      await progressService.updateProgress(
+        payload.progressJobId,
+        { processedCount: summary.fetched },
+        progressContext,
+      )
+
+      if (batch.anomaly) {
+        anomaly = batch.anomaly
+        // Re-running the page we could not trust is safe, because ingest keys on the
+        // provider's call id and updates in place.
+        summary.resumeCursor = batch.anomalyCursor ?? cursor
+        break
+      }
+
+      cursor = batch.nextCursor ?? null
+      if (!cursor) break
+    }
+
+    // A cursor surviving the loop means the batch cap ended it, not the provider.
+    if (!anomaly && cursor) summary.resumeCursor = cursor
+
+    if (anomaly || summary.resumeCursor) {
+      summary.truncated = true
+      const failure = describeTruncation(summary, anomaly)
+      logger.warn('the Tillio pull did not cover the whole range', {
+        progressJobId: payload.progressJobId,
+        code: failure.code,
+        anomaly,
+        resumeCursor: summary.resumeCursor,
+      })
+      // No in-between job state exists, and a sweep that silently skipped calls must not read
+      // as a clean one. The counts and the resume point ride along so the failure still says
+      // what landed and where to pick it up; the calls already ingested stay committed.
+      await progressService.failJob(
+        payload.progressJobId,
+        {
+          errorMessage: failure.message,
+          resultSummary: { ...summary, code: failure.code, ...(anomaly ? { anomaly } : {}) },
+        },
+        progressContext,
+      )
+      return summary
+    }
+
+    await progressService.completeJob(
+      payload.progressJobId,
+      { resultSummary: { ...summary } },
+      progressContext,
+    )
+    return summary
+  } catch (err) {
+    const failure = describeFailure(err)
+    logger.error('the Tillio pull failed', { progressJobId: payload.progressJobId, code: failure.code, err })
+    try {
+      await progressService.failJob(
+        payload.progressJobId,
+        {
+          errorMessage: failure.message,
+          errorStack: err instanceof Error ? err.stack?.slice(0, 10000) : undefined,
+          resultSummary: { ...summary, code: failure.code },
+        },
+        progressContext,
+      )
+    } catch (failErr) {
+      logger.error('failed to mark the pull progress job as failed', {
+        progressJobId: payload.progressJobId,
+        err: failErr,
+      })
+    }
+    throw err
+  }
+}

package/src/modules/tillio/lib/pull-readiness.ts

@@ -0,0 +1,77 @@
+import { computeEnvFingerprint, type TillioOperatorRecord } from './operators-store'
+import type { TillioResolvedEnvironment } from './operators'
+
+// The two levels the environment alone can be blocked at. Pulling and attaching an operator ask
+// different questions of the operator level, but the same question of this one, so they share it:
+// the `enabled` term was once written out in both places and one copy drifted.
+export type EnvironmentBlocker = 'integration_disabled' | 'environment_not_ready'
+
+export type PullBlocker = EnvironmentBlocker | 'operator_missing' | 'environment_drift'
+
+export type EnvironmentReadiness = {
+  ready: boolean
+  blocker: EnvironmentBlocker | null
+}
+
+export type EvaluateEnvironmentReadinessInput = {
+  environment: TillioResolvedEnvironment | null
+  integrationEnabled: boolean
+  environmentHealthy: boolean
+}
+
+export function evaluateEnvironmentReadiness(input: EvaluateEnvironmentReadinessInput): EnvironmentReadiness {
+  const ready = Boolean(input.environment) && input.integrationEnabled && input.environmentHealthy
+  // A switched-off integration is reported ahead of health because re-running a health check would
+  // not change anything while it is off - but only once there is something to switch on. A missing
+  // integration row also reads as disabled, so reporting that first on a fresh install would tell
+  // the user to enable an integration they have not configured yet, instead of to configure it.
+  if (!input.integrationEnabled && input.environment) return { ready, blocker: 'integration_disabled' }
+  if (!ready) return { ready, blocker: 'environment_not_ready' }
+  return { ready, blocker: null }
+}
+
+export type PullReadiness = {
+  environmentReady: boolean
+  operatorAttached: boolean
+  envDrift: boolean
+  blocker: PullBlocker | null
+}
+
+export type EvaluatePullReadinessInput = {
+  environment: TillioResolvedEnvironment | null
+  integrationEnabled: boolean
+  environmentHealthy: boolean
+  operator: TillioOperatorRecord | null
+}
+
+export function evaluatePullReadiness(input: EvaluatePullReadinessInput): PullReadiness {
+  const environment = evaluateEnvironmentReadiness(input)
+  const environmentReady = environment.ready
+  const operatorAttached = Boolean(input.operator)
+  const envDrift =
+    Boolean(input.environment) &&
+    Boolean(input.operator) &&
+    input.operator!.envFingerprint !== computeEnvFingerprint(input.environment!)
+
+  // Ordered so the reported blocker is the one the user can act on first: an unhealthy environment
+  // makes operator state meaningless, and drift only matters once both levels exist. Each code
+  // routes the UI to the settings section that fixes it.
+  if (environment.blocker) {
+    return { environmentReady, operatorAttached, envDrift, blocker: environment.blocker }
+  }
+  if (!operatorAttached) return { environmentReady, operatorAttached, envDrift, blocker: 'operator_missing' }
+  if (envDrift) return { environmentReady, operatorAttached, envDrift, blocker: 'environment_drift' }
+  return { environmentReady, operatorAttached, envDrift, blocker: null }
+}
+
+export const PULL_BLOCKER_MESSAGES: Record<PullBlocker, string> = {
+  integration_disabled: 'The Tillio integration is disabled. Enable it before pulling calls.',
+  environment_not_ready: 'Configure the Tillio environment and run the health check first.',
+  operator_missing: 'Attach a Tillio operator before pulling calls.',
+  environment_drift: 'The environment changed after this operator was attached. Detach and attach it again before pulling calls.',
+}
+
+export function blockerSection(blocker: PullBlocker): 'environment' | 'operator' {
+  if (blocker === 'integration_disabled' || blocker === 'environment_not_ready') return 'environment'
+  return 'operator'
+}