Skip to content

Enterprise agent platform for building, deploying, and operating AI teammates.

43.9 KB
Raw Blame
// Client for the per-task connector-runtime endpoints and the pure
// classification/routing rules the connector-runtime dialog builds on. This
// file (and every symbol it exports) has exactly one production consumer:
// the connector-runtime dialog and the app-chat context that opens it. It is
// not a general connector client -- it does not know about connection
// management, only about the two endpoints that read and write a task's
// missing runtime inputs.
import type { TranslationKey } from "@/i18n/translations"
import type { ClientErrorCode } from "@/lib/client-errors"
import { apiRequest, isJsonRecord, parseApiResponse, type ParsedApiResponse } from "@/lib/api-wrapper"
import { getApiUrl } from "@/lib/utils"

// section and type are closed sets on the wire (schemas/connector_runtime.py);
// a client may switch on them exhaustively, and adding a member is a wire
// change. Kept as `as const` arrays so a test can bind its parameterized rows
// to these members instead of re-typing the set by hand.
export const CONNECTOR_RUNTIME_SECTIONS = ["context", "secrets", "auth_selector"] as const
export type ConnectorRuntimeSection = (typeof CONNECTOR_RUNTIME_SECTIONS)[number]

export const CONNECTOR_RUNTIME_TYPES = ["string", "object"] as const
export type ConnectorRuntimeType = (typeof CONNECTOR_RUNTIME_TYPES)[number]

export interface ConnectorRuntimeRef {
  connector_type: string
  connector_id: number
}

export interface ConnectorRuntimeInput {
  section: ConnectorRuntimeSection
  key: string
  type: ConnectorRuntimeType
  required: boolean
  satisfied: boolean
  expired: boolean
}

export interface ConnectorRuntimeConnector {
  connector_ref: ConnectorRuntimeRef
  name: string
  inputs: ConnectorRuntimeInput[]
}

export interface ConnectorRuntimeReport {
  satisfied: boolean
  secrets_expires_at: string | null
  connectors: ConnectorRuntimeConnector[]
}

function isConnectorRuntimeSection(value: unknown): value is ConnectorRuntimeSection {
  return (CONNECTOR_RUNTIME_SECTIONS as readonly unknown[]).includes(value)
}

function isConnectorRuntimeType(value: unknown): value is ConnectorRuntimeType {
  return (CONNECTOR_RUNTIME_TYPES as readonly unknown[]).includes(value)
}

function readConnectorRuntimeRef(value: unknown): ConnectorRuntimeRef | null {
  if (!isJsonRecord(value)) return null
  if (typeof value.connector_type !== "string") return null
  if (typeof value.connector_id !== "number") return null
  return { connector_type: value.connector_type, connector_id: value.connector_id }
}

function readConnectorRuntimeInput(value: unknown): ConnectorRuntimeInput | null {
  if (!isJsonRecord(value)) return null
  const { section, key, type, required, satisfied, expired } = value
  if (!isConnectorRuntimeSection(section)) return null
  if (typeof key !== "string") return null
  if (!isConnectorRuntimeType(type)) return null
  if (typeof required !== "boolean") return null
  if (typeof satisfied !== "boolean") return null
  if (typeof expired !== "boolean") return null
  return { section, key, type, required, satisfied, expired }
}

function readConnectorRuntimeConnector(value: unknown): ConnectorRuntimeConnector | null {
  if (!isJsonRecord(value)) return null
  const connectorRef = readConnectorRuntimeRef(value.connector_ref)
  if (!connectorRef) return null
  if (typeof value.name !== "string") return null
  if (!Array.isArray(value.inputs)) return null
  const inputs: ConnectorRuntimeInput[] = []
  for (const rawInput of value.inputs) {
    const input = readConnectorRuntimeInput(rawInput)
    if (!input) return null
    inputs.push(input)
  }
  return { connector_ref: connectorRef, name: value.name, inputs }
}

/**
 * Validates an unknown value against the closed report shape. Never throws:
 * any cell that does not fit -- an unrecognized `section`/`type`, a missing
 * field, a non-array `connectors` -- returns null rather than a partially
 * trusted object. A future caller must not soften an unrecognized `section`
 * or `type` into a guessed member (`"context"`/`"string"`); the server
 * treats both fields as closed and a silent fallback would render a field
 * the server has not actually declared as fillable.
 */
export function readConnectorRuntimeReport(value: unknown): ConnectorRuntimeReport | null {
  if (!isJsonRecord(value)) return null
  const { satisfied, secrets_expires_at, connectors } = value
  if (typeof satisfied !== "boolean") return null
  if (secrets_expires_at !== null && typeof secrets_expires_at !== "string") return null
  if (!Array.isArray(connectors)) return null
  const parsedConnectors: ConnectorRuntimeConnector[] = []
  for (const rawConnector of connectors) {
    const connector = readConnectorRuntimeConnector(rawConnector)
    if (!connector) return null
    parsedConnectors.push(connector)
  }
  return { satisfied, secrets_expires_at, connectors: parsedConnectors }
}

// The seven status codes the read endpoint's own failure paths can return
// (see the per-task read endpoint's own docstring); anything else that is
// not 200 is still a read failure, it just does not need its own entry here.
export const READ_FAILURE_STATUSES = [400, 401, 403, 404, 422, 500, 503] as const

/**
 * How long either call below waits before giving up on a request that is not
 * answering. Nothing else cancels these two: the dialog's read effect drops a
 * late answer but does not stop the request behind it, and the save runs to
 * completion on purpose even when the dialog unmounts mid-flight. Without a
 * bound here, a request that never finishes answering -- no response at all,
 * or headers with a body that never arrives -- leaves the dialog unable to
 * save and, while the save is the call in flight, unable to close at all.
 *
 * The one comparable constant in this frontend is api-wrapper's
 * AUTH_REFRESH_TIMEOUT_MS (15s, for the token refresh). These two calls are
 * the heavier pair -- the write endpoint runs a full validation pass and one
 * encryption before it answers -- so this is one notch longer rather than a
 * number carried in from somewhere outside this repository.
 */
const CONNECTOR_RUNTIME_REQUEST_TIMEOUT_MS = 20_000

interface AnsweredConnectorRuntimeRequest {
  response: Response
  parsed: ParsedApiResponse
}

/**
 * Runs one connector-runtime request under the timeout above and hands back
 * both the response and its parsed body. Throws if the request does not get
 * that far in time.
 *
 * Both of apiRequest's paths forward the whole RequestInit to fetch -- direct
 * with no stored token, through withBearer and fetchWithRetry with one -- so
 * the signal reaches every attempt without api-wrapper's shared helpers
 * needing to know this timeout exists, and callers that pass no signal keep
 * behaving exactly as before.
 *
 * The body is read here rather than by the callers, because fetch resolves
 * as soon as the response *headers* arrive: a server that sends headers and
 * then stalls would leave `response.text()` waiting with no bound on it at
 * all, which is the unbounded wait this timeout exists to rule out. Holding
 * the read inside the window costs the callers nothing they did not already
 * do -- both parse every response they get -- except that a non-200 read
 * response now has its body parsed too, and that parse is discarded unread
 * exactly as before (this endpoint's `detail` string is never shown).
 *
 * Shaped like api-wrapper's own performTokenRefresh: an explicit controller
 * and timer rather than AbortSignal.timeout, because the timer has to be
 * cleared on the way out -- a request that answered in time must not leave a
 * pending abort behind it.
 *
 * No distinct failure kind for a timeout: both callers below already map a
 * rejection to `transport`, which is what a request that never answered is
 * from the caller's side.
 */
async function requestConnectorRuntime(
  url: string,
  init: RequestInit = {},
): Promise<AnsweredConnectorRuntimeRequest> {
  const controller = new AbortController()
  const timer = setTimeout(() => controller.abort(), CONNECTOR_RUNTIME_REQUEST_TIMEOUT_MS)
  try {
    const response = await apiRequest(url, { ...init, signal: controller.signal })
    const parsed = await parseApiResponse(response)
    // An aborted body read does not reach here as a rejection the way an
    // aborted fetch does: parseApiResponse turns it into an empty body
    // (`response.text().catch(() => "")`, api-wrapper.ts). So a body this
    // timeout cut short would arrive looking like a well-formed empty
    // response, which both callers report as `malformed` -- their word for a
    // server bug, carrying no retry. Reading the signal is what tells a
    // cut-short read apart from a genuinely empty one.
    if (controller.signal.aborted) throw new Error("connector-runtime request timed out")
    return { response, parsed }
  } finally {
    clearTimeout(timer)
  }
}

export type FetchTaskConnectorRuntimeRequirementsResult =
  | { ok: true; report: ConnectorRuntimeReport }
  | { ok: false; kind: "transport" }
  | { ok: false; kind: "http"; status: number }
  | { ok: false; kind: "malformed" }

/**
 * GET /api/chat/task/{task_id}/connector-runtime-requirements. Never throws:
 * a transport failure, a non-200 response, or a 200 whose body does not
 * parse into a report all come back as a tagged failure, kept distinct from
 * "read a report that says nothing is missing" -- collapsing the two would
 * make a task whose read genuinely fails look permanently satisfied. The
 * response body's `detail` string is never read: it is the server's English
 * safe message, not something to show a user. A request whose headers and
 * body are not both in hand within CONNECTOR_RUNTIME_REQUEST_TIMEOUT_MS is
 * abandoned and reported the same way as any other transport failure.
 */
export async function fetchTaskConnectorRuntimeRequirements(
  taskId: number,
): Promise<FetchTaskConnectorRuntimeRequirementsResult> {
  let answered: AnsweredConnectorRuntimeRequest
  try {
    answered = await requestConnectorRuntime(
      `${getApiUrl()}/api/chat/task/${taskId}/connector-runtime-requirements`,
    )
  } catch {
    return { ok: false, kind: "transport" }
  }
  const { response, parsed } = answered
  if (!response.ok) return { ok: false, kind: "http", status: response.status }
  const report = readConnectorRuntimeReport(parsed.data)
  if (!report) return { ok: false, kind: "malformed" }
  return { ok: true, report }
}

export interface ConnectorRuntimeSubmitItem {
  connector_ref: ConnectorRuntimeRef
  context: Record<string, unknown>
}

export type SubmitTaskConnectorRuntimeValuesFailure =
  | { ok: false; kind: "transport" }
  | {
    ok: false
    kind: "coded"
    status: number
    code: string
    reason?: string
    connectorRef?: ConnectorRuntimeRef
  }
  | { ok: false; kind: "http"; status: number }
  | { ok: false; kind: "malformed" }

export type SubmitTaskConnectorRuntimeValuesResult =
  | { ok: true; report: ConnectorRuntimeReport }
  | SubmitTaskConnectorRuntimeValuesFailure

function readSubmitErrorEnvelope(
  value: unknown,
): { code: string; reason?: string; connectorRef?: ConnectorRuntimeRef } | null {
  if (!isJsonRecord(value)) return null
  const error = value.error
  if (!isJsonRecord(error)) return null
  if (typeof error.code !== "string") return null
  const details = isJsonRecord(error.details) ? error.details : null
  // A key is present-with-any-value (including "") the moment its type is
  // string; absent -- the 503 shape that carries no reason at all -- is a
  // different input from present-and-empty, so this must not fall back to
  // `|| undefined`.
  const reason = details && typeof details.reason === "string" ? details.reason : undefined
  const connectorRef = details ? readConnectorRuntimeRef(details.connector_ref) ?? undefined : undefined
  return { code: error.code, reason, connectorRef }
}

/**
 * POST /api/chat/task/{task_id}/connector-runtime-values. Never throws.
 * Distinguishes four failure shapes because the write endpoint's non-200
 * responses are not uniform: some carry the `{"error": {...}}` envelope
 * (a `ConnectorRuntimeError`), the task-not-found 404 does not, and a 200
 * whose body fails report validation is its own case (a server bug, not a
 * network problem). A 200 response does not by itself mean the connector is
 * now satisfied -- resolveDialogOutcome decides that from the returned
 * report, not from this function's `ok` flag. A request whose headers and
 * body are not both in hand within CONNECTOR_RUNTIME_REQUEST_TIMEOUT_MS is
 * abandoned and reported as a transport failure; the values it carried may or
 * may not have been written, which is already true of every other transport
 * failure on this endpoint.
 */
export async function submitTaskConnectorRuntimeValues(
  taskId: number,
  items: ConnectorRuntimeSubmitItem[],
): Promise<SubmitTaskConnectorRuntimeValuesResult> {
  let answered: AnsweredConnectorRuntimeRequest
  try {
    answered = await requestConnectorRuntime(
      `${getApiUrl()}/api/chat/task/${taskId}/connector-runtime-values`,
      {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify({ items }),
      },
    )
  } catch {
    return { ok: false, kind: "transport" }
  }
  const { response, parsed } = answered
  if (response.ok) {
    const report = readConnectorRuntimeReport(parsed.data)
    return report ? { ok: true, report } : { ok: false, kind: "malformed" }
  }
  const envelope = readSubmitErrorEnvelope(parsed.data)
  if (!envelope) return { ok: false, kind: "http", status: response.status }
  return {
    ok: false,
    kind: "coded",
    status: response.status,
    code: envelope.code,
    reason: envelope.reason,
    connectorRef: envelope.connectorRef,
  }
}

// The enumerable exact-match `reason` strings the server raises alongside
// code `invalid_runtime_context`. classifySubmitFailure does not read this
// constant: it branches on the individual strings it has a specific
// disposition for and lets every other reason reach the generic fallthrough.
// The constant exists so a test can bind each member to the disposition it
// actually produces, which is what makes "a new reason silently becomes
// generic" a visible choice rather than an accident.
//
// Deliberately excludes the two "stored selection is corrupted" reason
// strings the server can produce (services/connector_runtime.py's
// _load_task_selected_refs): one of them interpolates a field name from
// whatever the corrupted row actually stored, so the full set is not
// enumerable, and neither string ever equals KEY_NAME_REJECTED_REASON below
// -- both fall through to the generic disposition instead.
export const CONNECTOR_RUNTIME_KNOWN_REASONS = [
  "empty_items",
  "empty_item_payload",
  "payload_too_large",
  "duplicate_ref",
  "connector_not_selected",
  "undeclared_context_key",
  "auth_selector_not_supported",
] as const

// The one exact sentence the per-turn gate raises for a malformed key name
// (validate_runtime_source_key in
// core/tools/adapters/vibe/connector_runtime.py). Written out rather than
// imported because this is TypeScript and that constant lives in the Python
// package; it mirrors that function's literal message, and a change to the
// message on that side has to be mirrored here.
export const KEY_NAME_REJECTED_REASON = "runtime input key must match [A-Za-z0-9_-]+"

const TYPE_MISMATCH_CONTEXT_PREFIX = "type_mismatch.context."
const EMPTY_VALUE_CONTEXT_PREFIX = "empty_value.context."
const CONFLICT_CONTEXT_PREFIX = "conflict.context."

export interface ConnectorRuntimeFailureLocation {
  connectorRef?: ConnectorRuntimeRef
  key?: string
}

// The full set of connectorRuntime.errors.* leaves classifySubmitFailure can
// select. Kept as a literal union (not `string`) so a caller mapping this to
// a translation key does so through an exhaustive lookup table rather than a
// template-literal key that a source scan cannot verify against the i18n
// tree (see the dialog component's own error-message lookup).
export type ConnectorRuntimeErrorMessageKey =
  | "network"
  | "busyRetry"
  | "contactAdmin"
  | "conflict"
  | "typeString"
  | "typeObject"
  | "typeUnknown"
  | "emptyValue"
  | "keyNameRejected"
  | "configChanged"
  | "notInSession"
  | "connectorUnavailable"
  | "tooLarge"

export interface ConnectorRuntimeFailureDisposition {
  messageKey: ConnectorRuntimeErrorMessageKey
  retry: boolean
  // Whether the dialog should re-read the report before the next submit. A
  // conflict disposition sets this because the stored value moved out from
  // under the user; the next `buildSubmitItems(refreshedReport, drafts)` call
  // already drops any key the refreshed report now reports satisfied, so no
  // separate "drop the keys the retry no longer needs" field is needed here.
  refresh: boolean
  locate: ConnectorRuntimeFailureLocation
}

function findDeclaredInputType(
  report: ConnectorRuntimeReport,
  connectorRef: ConnectorRuntimeRef | undefined,
  key: string,
): ConnectorRuntimeType | null {
  if (!connectorRef) return null
  for (const connector of report.connectors) {
    if (
      connector.connector_ref.connector_type !== connectorRef.connector_type
      || connector.connector_ref.connector_id !== connectorRef.connector_id
    ) continue
    for (const input of connector.inputs) {
      // Every type_mismatch reason this backs is section-scoped to "context"
      // (see locateFieldError in connector-runtime-dialog.tsx, which filters
      // the same way): without this filter a same-named "secrets" row could
      // win the search and report that row's declared type instead.
      if (input.section === "context" && input.key === key) return input.type
    }
  }
  return null
}

const GENERIC_DISPOSITION: ConnectorRuntimeFailureDisposition = {
  messageKey: "contactAdmin",
  retry: false,
  refresh: false,
  locate: {},
}

/**
 * The single place that turns a write failure into what the dialog shows,
 * whether the retry button appears, whether the report is re-read
 * automatically, and where the error attaches. Never throws. Judged in a
 * fixed order because two shapes both carry `code: "invalid_runtime_context"`
 * and an English `reason` (the malformed-key sentence and a corrupted stored
 * selection): only the malformed-key sentence is checked by exact text, so a
 * future call site must not loosen that check to "looks like English" --
 * that would misclassify a corrupted-selection failure as a fixable key name.
 * `report` is the dialog's own most recently read report, consulted only to
 * pick among the field-type dispositions (`typeString`/`typeObject`/
 * `typeUnknown`) for a mismatch reason that does not itself carry the
 * field's declared type.
 */
export function classifySubmitFailure(
  outcome: SubmitTaskConnectorRuntimeValuesFailure,
  report: ConnectorRuntimeReport,
): ConnectorRuntimeFailureDisposition {
  if (outcome.kind === "transport") {
    return { messageKey: "network", retry: true, refresh: false, locate: {} }
  }

  if (outcome.kind === "http") return GENERIC_DISPOSITION
  if (outcome.kind === "malformed") {
    return { ...GENERIC_DISPOSITION, refresh: true }
  }

  const { status, code, reason, connectorRef } = outcome

  if (status === 503 && code === "connector_runtime_unavailable" && reason === undefined) {
    return { messageKey: "busyRetry", retry: true, refresh: false, locate: {} }
  }
  // Any 503 with a reason key present (including an empty string) is treated
  // uniformly: the one case this client mints on purpose
  // (team_scope_resolution_failed) and any deployment-installed hook's own
  // 503 both land here, because neither is something a user retry fixes.
  if (status === 503 && reason !== undefined) return GENERIC_DISPOSITION

  if (
    status === 409
    && code === "runtime_context_immutable"
    && reason !== undefined
    && reason.startsWith(CONFLICT_CONTEXT_PREFIX)
  ) {
    const key = reason.slice(CONFLICT_CONTEXT_PREFIX.length)
    return { messageKey: "conflict", retry: false, refresh: true, locate: { connectorRef, key } }
  }

  if (status === 400 && code === "invalid_runtime_context" && reason !== undefined) {
    if (reason.startsWith(TYPE_MISMATCH_CONTEXT_PREFIX)) {
      const key = reason.slice(TYPE_MISMATCH_CONTEXT_PREFIX.length)
      const declaredType = findDeclaredInputType(report, connectorRef, key)
      // The connector's own edit endpoint writes a new declaration in place,
      // with no version and no snapshot held by the task -- so the type this
      // dialog read and the type the write endpoint just checked against can
      // differ. Refreshing here is what lets the row pick up the new
      // declaration on its next render, rather than staying keyed to the
      // stale one. The messageKey below is chosen against the pre-refresh
      // report passed into this call and is not itself recomputed after the
      // refresh; isTypeMismatchDispositionStale (below) is what the caller
      // checks against the refreshed report to clear this hint outright
      // when the row's type no longer matches it, instead of leaving a
      // type-specific message attached to a row that has since changed type.
      // Three answers, not two: "object", "string", and "this report
      // declares no type for this row at all" -- a rejection that carries
      // no connector_ref, or a row this report does not carry. Folding the
      // third into "string" tells the user a field needs text on the
      // strength of a declaration nobody ever read.
      return {
        messageKey: declaredType === null
          ? "typeUnknown"
          : declaredType === "object" ? "typeObject" : "typeString",
        retry: false,
        refresh: true,
        locate: { connectorRef, key },
      }
    }
    if (reason.startsWith(EMPTY_VALUE_CONTEXT_PREFIX)) {
      const key = reason.slice(EMPTY_VALUE_CONTEXT_PREFIX.length)
      return { messageKey: "emptyValue", retry: false, refresh: false, locate: { connectorRef, key } }
    }
    if (reason === KEY_NAME_REJECTED_REASON) {
      // The response never carries the offending key -- only which
      // connector it belongs to -- so this cannot locate a specific row.
      return { messageKey: "keyNameRejected", retry: false, refresh: false, locate: { connectorRef } }
    }
    if (reason === "undeclared_context_key") {
      return { messageKey: "configChanged", retry: false, refresh: true, locate: { connectorRef } }
    }
    if (reason === "connector_not_selected") {
      return { messageKey: "notInSession", retry: false, refresh: true, locate: { connectorRef } }
    }
    if (reason === "payload_too_large") {
      return { messageKey: "tooLarge", retry: false, refresh: false, locate: { connectorRef } }
    }
  }

  if (status === 404 && code === "connector_not_found") {
    return { messageKey: "connectorUnavailable", retry: false, refresh: true, locate: { connectorRef } }
  }

  // Closed set exhausted: an unrecognized code, a reason outside every
  // prefix and exact string matched above, or a corrupted stored selection's
  // unenumerable sentence. The reasons this client's own request-building
  // should never produce (empty_items, empty_item_payload, duplicate_ref)
  // and auth_selector_not_supported also land here: they carry nothing a
  // user can act on. A hook a deployment installs can raise a
  // ConnectorRuntimeError with any code/status of its own choosing, and it
  // lands here the same way.
  return GENERIC_DISPOSITION
}

/**
 * Whether a type hint on a disposition no longer matches the row it would
 * attach to, given a report re-read after the disposition's own
 * `refresh: true` landed. Three messageKeys carry a type hint:
 * `typeObject` and `typeString` name a declared type, and `typeUnknown`
 * says the report the hint was derived from named none. Every other
 * messageKey is never type-related, so this always reads false for it.
 *
 * This answers one question only: does the refreshed report still declare
 * the type the hint names. A row that report no longer declares under
 * "context", and one it now reports satisfied, both leave the two named
 * hints alone -- neither is a changed type, and neither means the save
 * stopped being rejected. What such a row does change is where the hint
 * can attach and therefore what it may claim: the dialog's field-error
 * location falls back to whole-dialog scope, where it is reworded to stop
 * naming a type no field on screen is asking for
 * (translateDialogScopeFailure in connector-runtime-dialog.tsx).
 *
 * What the dialog should then *do* about a hint this calls stale is not
 * this predicate's question, and the dialog does not ask it directly:
 * reconcileTypeMismatchDisposition below is the one caller, because two of
 * the three hints are dropped on a stale answer and one is re-derived.
 */
export function isTypeMismatchDispositionStale(
  disposition: ConnectorRuntimeFailureDisposition,
  refreshedReport: ConnectorRuntimeReport,
): boolean {
  const { messageKey } = disposition
  if (messageKey !== "typeObject" && messageKey !== "typeString" && messageKey !== "typeUnknown") return false
  const { connectorRef, key } = disposition.locate
  if (key === undefined) return false
  const currentType = findDeclaredInputType(refreshedReport, connectorRef, key)
  // The unknown hint's whole claim is "this report declares no type here",
  // so any declared type in the refreshed report ends that claim -- including
  // the type the server was enforcing all along, which is the common case.
  // Ending the claim is not the same as having nothing left to say, which is
  // why the reconciler below re-derives this one instead of dropping it.
  if (messageKey === "typeUnknown") return currentType !== null
  const expectedType = messageKey === "typeObject" ? "object" : "string"
  return currentType !== null && currentType !== expectedType
}

/**
 * What a type hint becomes once a report re-read after its own
 * `refresh: true` has landed: the same hint, a re-derived one, or none.
 *
 * Three answers rather than the two "keep it or drop it" the staleness
 * check alone gives, because a hint stops matching a refreshed report for
 * two opposite reasons. `typeObject`/`typeString` name a type the row has
 * since stopped declaring, and nothing in the refreshed report says what
 * the server was enforcing instead, so there is nothing left to say and
 * the hint goes. `typeUnknown` is the other way round: its whole claim is
 * that the report named no type here, and a refreshed report that does
 * name one answers exactly the question the hint said it could not. So it
 * is re-derived into the named hint rather than dropped -- dropping it
 * would take a rejection the user was shown off the screen while the draft
 * that provoked it is still in the box and the save button still live, and
 * the next save would be refused the same way for the same unstated
 * reason.
 *
 * The caller compares the result with what it passed in: the same object
 * back means nothing changed.
 */
export function reconcileTypeMismatchDisposition(
  disposition: ConnectorRuntimeFailureDisposition,
  refreshedReport: ConnectorRuntimeReport,
): ConnectorRuntimeFailureDisposition | null {
  if (!isTypeMismatchDispositionStale(disposition, refreshedReport)) return disposition
  if (disposition.messageKey !== "typeUnknown") return null
  const { connectorRef, key } = disposition.locate
  const currentType = key === undefined ? null : findDeclaredInputType(refreshedReport, connectorRef, key)
  // Unreachable: the staleness check calls an unknown-type hint stale only
  // when the refreshed report declares a type for this row. Kept as a guard
  // rather than a non-null assertion so that this function proves the fact
  // instead of assuming it, and so a future loosening of that check cannot
  // turn it into a hint naming a type nobody read.
  if (currentType === null) return null
  return { ...disposition, messageKey: currentType === "object" ? "typeObject" : "typeString" }
}

/**
 * Whether the connector-runtime dialog is a supported presence on the
 * current page. The failure notification that would open it reaches every
 * page an authenticated user can be on (the triggering frame is filtered
 * only by task identity, not by route), but the dialog is a UI surface for
 * exactly the pages a user fills it in from: the conversation page and the
 * two workforce run/edit pages. Everywhere else the existing failure bubble
 * is the only notification, same as before this dialog existed. This is a
 * product-surface decision, not an authorization boundary: whether a read or
 * write is *allowed* is decided solely by the per-task endpoints' own
 * owner-of-the-task check, and narrowing where the dialog appears can only
 * make it appear less, never grant it access it would not otherwise have.
 *
 * A first gate (a new conversation's held first message) may also show on
 * the two pages a conversation is started from: its create response lands
 * while the user is still there, before the navigation to the new
 * conversation has arrived. See isDialogHostPathFor.
 *
 * The static-export server (frontend_static.py) maps all three shapes to a
 * page shell -- a trailing slash and the `__shell__` placeholder id both
 * still match, so this holds under either deployment.
 */
export const CONNECTOR_RUNTIME_DIALOG_HOST_PATTERNS = [
  /^\/task\/[^/]+\/?$/,
  /^\/workforces\/[^/]+\/run\/?$/,
  /^\/workforces\/[^/]+\/?$/,
] as const

export function isConnectorRuntimeDialogHostPath(pathname: string | null): boolean {
  if (!pathname) return false
  return CONNECTOR_RUNTIME_DIALOG_HOST_PATTERNS.some(pattern => pattern.test(pathname))
}

// The new-conversation page and an agent's chat page: where a first gate's
// create response can land. Only a first gate adds them. The home page and
// the build list start conversations too, but they create the task without
// an agent_id, and the server reports a task with no agent as met, so
// shouldHoldFirstMessage never holds a message started there.
export const FIRST_GATE_EXTRA_HOST_PATTERNS = [/^\/task\/?$/, /^\/agent\/[^/]+\/?$/] as const

// The one route check the dialog runs, for the trigger of the request it shows.
export function isDialogHostPathFor(trigger: ConnectorRuntimeDialogTrigger, pathname: string | null): boolean {
  if (isConnectorRuntimeDialogHostPath(pathname)) return true
  return trigger === "first_gate" && FIRST_GATE_EXTRA_HOST_PATTERNS.some(pattern => pattern.test(pathname ?? ""))
}

// The three terminal task_error codes that open the dialog. The other
// two connector-runtime codes the client error table knows about --
// invalid_runtime_context, connector_runtime_unavailable -- settle the turn
// without anything left for this dialog to collect: the first means the
// server-stored selection or a declared key is itself invalid, the second
// means a dependency the gate needs is down, and neither is answered by
// filling in a context value.
export const CONNECTOR_RUNTIME_DIALOG_TRIGGER_CODES = [
  "missing_runtime_context",
  "runtime_secret_unavailable",
  "scheduled_secret_unavailable",
] as const

export function isConnectorRuntimeDialogTriggerCode(
  code: ClientErrorCode,
): code is (typeof CONNECTOR_RUNTIME_DIALOG_TRIGGER_CODES)[number] {
  return (CONNECTOR_RUNTIME_DIALOG_TRIGGER_CODES as readonly string[]).includes(code)
}

export const DIALOG_OUTCOME_KINDS = ["met", "unsupported_only", "nothing_fillable", "fillable"] as const
export type DialogOutcomeKind = (typeof DIALOG_OUTCOME_KINDS)[number]

export interface ConnectorRuntimeInputLocation {
  connectorRef: ConnectorRuntimeRef
  key: string
}

export type DialogOutcome =
  | { kind: "met" }
  | { kind: "unsupported_only"; blocking: ConnectorRuntimeInputLocation[] }
  | { kind: "nothing_fillable" }
  | { kind: "fillable"; blocking: ConnectorRuntimeInputLocation[] }

/**
 * The single derivation both "should the dialog open" and "should it close
 * after a save" read from: never recomputed per-key, always
 * `report.satisfied` for "met" -- a report can have every required key
 * satisfied yet carry a top-level `false` (one malformed-but-optional
 * secrets key forces the aggregate false; services/connector_runtime.py's
 * aggregation rule), and recomputing from the per-key flags here would read
 * that report as met when the server does not consider it so. Two groups
 * partition every unsatisfied *required* input: "A" (`context`, something
 * this dialog can still collect) and "S" (`secrets`/`auth_selector`,
 * required but not fillable in this phase). Optional inputs never appear in
 * `blocking` -- an unfilled optional secret is not something to tell the
 * user "is still needed".
 */
export function resolveDialogOutcome(report: ConnectorRuntimeReport): DialogOutcome {
  if (report.satisfied) return { kind: "met" }

  const blockingA: ConnectorRuntimeInputLocation[] = []
  const blockingS: ConnectorRuntimeInputLocation[] = []
  for (const connector of report.connectors) {
    for (const input of connector.inputs) {
      if (!input.required || input.satisfied) continue
      const location = { connectorRef: connector.connector_ref, key: input.key }
      if (input.section === "context") blockingA.push(location)
      else blockingS.push(location)
    }
  }

  if (blockingA.length === 0 && blockingS.length === 0) return { kind: "nothing_fillable" }
  if (blockingA.length === 0) return { kind: "unsupported_only", blocking: blockingS }
  return { kind: "fillable", blocking: blockingS }
}

// Why a dialog request was opened. Kept here so the dialog's pure modules
// and its provider can both name it without this module importing either.
export type ConnectorRuntimeDialogTrigger = "turn_failure" | "session_open" | "first_gate"

export type ConnectorRuntimeDialogAction = "saveAndResend" | "saveOnly" | "acknowledge" | "saveAndSend" | "sendHeld"

/**
 * How a request opened for `trigger` reads a report: the dialog's first read,
 * its save and its render all ask this. A first gate holds a message the user
 * has not sent yet, so for it "fillable" means a missing required context key
 * this dialog can actually save. A key whose name the server rejects
 * (isAcceptedRuntimeKeyName) cannot be saved from anywhere -- the write fails
 * with keyNameRejected -- so a first gate counts it with the inputs it cannot
 * fill: without an acceptable one left, the report reads as unsupported_only
 * (secrets still missing) or nothing_fillable, and the message goes out to
 * fail at the per-turn check as it does today, instead of waiting behind a
 * dialog that can never send it. Every other trigger reads
 * resolveDialogOutcome unchanged.
 */
export function resolveOutcomeFor(report: ConnectorRuntimeReport, trigger: ConnectorRuntimeDialogTrigger): DialogOutcome {
  const outcome = resolveDialogOutcome(report)
  if (trigger !== "first_gate" || outcome.kind !== "fillable") return outcome
  const savable = report.connectors.some(connector => connector.inputs.some(input => (
    input.required && !input.satisfied && input.section === "context" && isAcceptedRuntimeKeyName(input.key)
  )))
  if (savable) return outcome
  return outcome.blocking.length > 0 ? { kind: "unsupported_only", blocking: outcome.blocking } : { kind: "nothing_fillable" }
}

/**
 * Whether a web-chat create response asks for the first message to be held
 * until the task's missing runtime inputs are filled: the same reading a
 * first gate gives every later report (resolveOutcomeFor), so the message is
 * held only while there is something the user can save here. Reads the
 * create response's report only for this decision: that report is computed
 * from the agent before the task exists (every key reads unsatisfied), so
 * what the dialog shows always comes from the per-task read. Anything that
 * does not parse -- null on the public and share create paths, a missing
 * field, a malformed body -- answers "do not hold", the behavior before this
 * check.
 */
export function shouldHoldFirstMessage(value: unknown): boolean {
  const report = readConnectorRuntimeReport(value)
  return report !== null && resolveOutcomeFor(report, "first_gate").kind === "fillable"
}

// The one sentence a create path shows when its held first message was
// cleared by anything other than the user.
export const FIRST_GATE_CLEARED_MESSAGE_KEY = "connectorRuntime.firstGateCleared" as const satisfies TranslationKey

/**
 * A first gate's buttons: fill in and send while something is fillable,
 * otherwise send the held message as it is. Never "Got it", which closes as
 * dismissed and would drop a message the user never chose to drop; every
 * other request uses resolveDialogActions.
 */
export function resolveFirstGateActions(outcome: DialogOutcome): ConnectorRuntimeDialogAction[] {
  switch (outcome.kind) {
    case "fillable":
      return ["saveAndSend"]
    case "met":
    case "unsupported_only":
    case "nothing_fillable":
      return ["sendHeld"]
    default: {
      // Same exhaustiveness guard as resolveDialogActions.
      const unhandled: never = outcome
      void unhandled
      return ["sendHeld"]
    }
  }
}

/**
 * The dialog's button set, derived from the outcome and whether this
 * request carries a resend snapshot -- never from whether the provider's
 * stash is non-empty, which is cleared the moment the snapshot is handed to
 * the request; reading the stash here instead would make the resend button
 * disappear right after the handoff that is supposed to enable it.
 *
 * Every outcome maps to at least one button, `met` included. A met report
 * normally closes the dialog before it renders: the first read does, and so
 * does a save, once any resend it promised has settled. Three paths still
 * render one in an open dialog -- the refresh a failed save triggers, a
 * same-task re-request's read that finds nothing missing, and a
 * save-and-resend's own successful save while its resend is still in flight
 * -- and returning no buttons there left the footer empty with only the
 * window chrome's close control to get out of it.
 */
export function resolveDialogActions(
  outcome: DialogOutcome,
  hasResendPayload: boolean,
): ConnectorRuntimeDialogAction[] {
  switch (outcome.kind) {
    case "fillable":
      return hasResendPayload ? ["saveAndResend", "saveOnly"] : ["saveOnly"]
    case "met":
    case "unsupported_only":
    case "nothing_fillable":
      return ["acknowledge"]
    default: {
      // Listing the acknowledge kinds instead of defaulting to them is what
      // makes this assignment stop compiling once a kind is added to
      // DialogOutcomeKind without a case here, rather than letting the new
      // kind inherit a button set nobody chose for it. The return below
      // still keeps a footer from rendering empty if a value from outside
      // the union reaches this at runtime.
      const unhandled: never = outcome
      void unhandled
      return ["acknowledge"]
    }
  }
}

/**
 * Shared by the dialog's draft state and buildSubmitItems so a draft value
 * written under one key is always read back under the same key. Keyed by the
 * input's full identity -- connector, section, key name and declared type --
 * not just connector and key name: the connector's own edit endpoint can
 * change a key's declared type in place between the report a draft was
 * written against and the next one the dialog reads (no version, no
 * per-task snapshot), and two different sections of the same connector may
 * legitimately reuse a key name. Including type means a stale draft cannot
 * silently survive a type change under a new, unrelated meaning; including
 * section means two same-named rows in different sections never collide,
 * including as React list keys (the dialog reuses this same string there).
 */
export function connectorRuntimeInputDraftKey(
  ref: ConnectorRuntimeRef,
  section: ConnectorRuntimeSection,
  key: string,
  type: ConnectorRuntimeType,
): string {
  return `${ref.connector_type}:${ref.connector_id}:${section}:${key}:${type}`
}

/**
 * Whether a parsed JSON value is an object-typed context draft worth
 * submitting: a plain object (not an array, not null) with at least one key.
 * An empty object parses as valid JSON, but the server's own blank check
 * (`not value` for an object-typed context field) treats `{}` as empty and
 * 400s the whole submission, taking every other filled-in key in the same
 * batch down with it -- so this is the one predicate both the dialog's blur
 * validation and buildSubmitItems below read, instead of each hand-rolling
 * its own "is this submittable" check and drifting apart on `{}`.
 *
 * Built on api-wrapper's isJsonRecord rather than restating the plain-object
 * test, so the dialog -- which needs the two halves apart, to tell an empty
 * object from a value that is no object at all -- reads the same plain-object
 * rule this does instead of a second copy of it.
 */
export function isSubmittableObjectValue(parsed: unknown): boolean {
  return isJsonRecord(parsed) && Object.keys(parsed).length > 0
}

/**
 * The context-section items worth submitting: unsatisfied, non-blank. Reads
 * `section === "context"` explicitly rather than `!satisfied` alone --
 * `secrets`/`auth_selector` rows are also always `satisfied: false` in this
 * phase, and the request body has no field for either, so including them
 * would submit a shape the server 422s. Does not consult `required`: a
 * `fillable` dialog lets a user fill in an optional context key too, and
 * this is the one place that decides what actually gets submitted for a
 * connector, keyed by the connector_ref exactly as the report gave it (never
 * the whole connector object, which the request schema does not accept
 * extra fields on without a silent drop, schemas/connector_runtime.py:112).
 */
export function buildSubmitItems(
  report: ConnectorRuntimeReport,
  drafts: Record<string, string>,
): ConnectorRuntimeSubmitItem[] {
  const items: ConnectorRuntimeSubmitItem[] = []
  for (const connector of report.connectors) {
    const context: Record<string, unknown> = {}
    for (const input of connector.inputs) {
      if (input.section !== "context" || input.satisfied) continue
      const rawValue = drafts[connectorRuntimeInputDraftKey(connector.connector_ref, input.section, input.key, input.type)]
      if (rawValue === undefined) continue
      if (input.type === "string") {
        // Submit the trimmed value, not the raw one. The server's merge makes
        // a stored context value immutable, so surrounding whitespace a paste
        // carried in would be written permanently: resubmitting the same
        // secret without it returns 409 runtime_context_immutable, and the
        // only recovery left is a new task.
        const value = rawValue.trim()
        if (value === "") continue
        context[input.key] = value
      } else {
        let parsed: unknown
        try {
          parsed = JSON.parse(rawValue)
        } catch {
          continue
        }
        if (!isSubmittableObjectValue(parsed)) continue
        context[input.key] = parsed
      }
    }
    if (Object.keys(context).length === 0) continue
    items.push({ connector_ref: connector.connector_ref, context })
  }
  return items
}

/**
 * The submit button's only enabling rule: at least one submittable key, and
 * `hasInvalidObjectDraft` is false. That flag means an invalid-object draft
 * on a row the current report still offers an editable control for --
 * deciding which marks are still live is the caller's job, not this
 * function's; a mark against a row the report no longer renders as editable
 * must not reach this parameter. Never adds "every required key filled" --
 * that would be a second, independently-maintained copy of the server's own
 * completeness rule, the exact drift the design forbids. A malformed
 * key-name warning never participates here either: it is informational, and
 * the row it warns about can still be submitted (the server, not this rule,
 * is the one that will reject it).
 */
export function isSubmitEnabled(items: ConnectorRuntimeSubmitItem[], hasInvalidObjectDraft: boolean): boolean {
  return items.length > 0 && !hasInvalidObjectDraft
}

// Mirrors core/tools/adapters/vibe/connector_runtime.py's
// validate_runtime_source_key exactly. It never participates in submission
// gating: it drives the row hint, and whether a first gate counts a required
// context key as something the user can still fill (resolveOutcomeFor). A
// server-side rename of the accepted character set would require updating
// this constant to match.
const ACCEPTED_RUNTIME_KEY_NAME_RE = /^[A-Za-z0-9_-]+$/

export function isAcceptedRuntimeKeyName(key: string): boolean {
  return ACCEPTED_RUNTIME_KEY_NAME_RE.test(key)
}