@ai-matrx/chat 0.1.74 → 0.2.0

package/dist/agents/connectors/attachments.slice.d.ts

@@ -0,0 +1,121 @@
+/**
+ * What is attached to THIS conversation — the durable half of the two-kinds
+ * split (`features/connectors/attachable-resources.ts`).
+ *
+ * Two states live here and they are not the same thing:
+ *
+ *   `rows`    — attachments the server has, read back from
+ *               `GET /conversations/{id}/attachments`. These survive a reload
+ *               because they are association edges, not browser state.
+ *   `pending` — picks CARRIED IN from somewhere else (an agent switch copies
+ *               the source chat's selections forward) that have not yet been
+ *               written to this conversation.
+ *
+ * 🚨 `pending` is NOT a `/chat/new` holding pen any more. The server creates
+ * the conversation row on the first write against the browser-minted id
+ * (aidream 7e7ebf6da2), so a pick made on `/chat/new` is POSTed the moment it
+ * is made and comes back as a real row. Holding it would mean showing a chip
+ * for something the server has never heard of — the optimistic lie a reload
+ * exposes. The only picks that wait are the inherited ones, and they are
+ * flushed the instant the read of this conversation succeeds.
+ *
+ * 🚨 A FAILED READ IS NEVER AN EMPTY LIST. `status: "failed"` + `error` is a
+ * distinct state from "nothing attached", and the surfaces render it as such.
+ * Collapsing them is the lie that a green checkmark told over a dead MCP
+ * connection (Arman, 2026-09-13).
+ */
+import { type ConversationAttachment, type PendingAttachment } from "./attachable-resources.js";
+export type AttachmentsStatus = "idle" | "loading" | "succeeded" | "failed";
+export interface ConversationAttachmentsEntry {
+    rows: ConversationAttachment[];
+    pending: PendingAttachment[];
+    status: AttachmentsStatus;
+    error: string | null;
+    /** Attachment keys with a write in flight — per-row busy, never a page spinner. */
+    busyKeys: string[];
+    /** The last write that failed, with the server's own sentence. */
+    writeError: string | null;
+    /** Keys inherited during an agent switch, retained as removal tombstones. */
+    handoffInheritedKeys: string[];
+    /** Inherited picks explicitly removed on this destination. */
+    handoffRemovedKeys: string[];
+}
+export interface AttachmentsSliceState {
+    byConversationId: Record<string, ConversationAttachmentsEntry>;
+}
+/**
+ * The stable "nothing known yet" entry. Exported because every consumer must
+ * coalesce to the SAME object — a fresh `{}` per render would re-run every
+ * effect downstream of it forever.
+ */
+export declare const EMPTY_ATTACHMENTS_ENTRY: ConversationAttachmentsEntry;
+export declare const loadConversationAttachments: import("@reduxjs/toolkit").AsyncThunk<{
+    conversationId: string;
+    rows: any;
+}, {
+    conversationId: string;
+}, import("@reduxjs/toolkit").AsyncThunkConfig>;
+/**
+ * Attach one pick — ALWAYS a real request, including on `/chat/new`.
+ *
+ * The server creates the conversation row on first write against the minted id
+ * (aidream 7e7ebf6da2), so there is no window in which a pick has nothing to
+ * POST to. The old `conversationExists` hold existed only because that POST
+ * used to 404; keeping it after the 404 was gone would mean the chip showed a
+ * pick the server had never heard of — an optimistic lie that a reload erases.
+ *
+ * What comes back is the server's own row, so the chip and the picker state
+ * are the server's answer, never the browser's hope.
+ */
+export declare const attachResource: import("@reduxjs/toolkit").AsyncThunk<{
+    conversationId: string;
+    pick: PendingAttachment;
+    row: any;
+}, {
+    conversationId: string;
+    pick: PendingAttachment;
+}, import("@reduxjs/toolkit").AsyncThunkConfig>;
+/**
+ * Send every held pick to a conversation that now exists.
+ *
+ * Partial success is the normal case worth designing for: four picks, one
+ * provider revoked in between. Each pick is settled on its own, landed ones
+ * clear, and the ones that failed stay pending WITH the reason, so nothing
+ * disappears quietly.
+ */
+export declare const flushPendingAttachments: import("@reduxjs/toolkit").AsyncThunk<{
+    conversationId: string;
+    landed: ConversationAttachment[];
+    failed: {
+        pick: PendingAttachment;
+        error: string;
+    }[];
+}, {
+    conversationId: string;
+}, import("@reduxjs/toolkit").AsyncThunkConfig>;
+/** Remove a landed attachment. A pending pick is dropped by `dropPendingAttachment`. */
+export declare const detachResource: import("@reduxjs/toolkit").AsyncThunk<{
+    conversationId: string;
+    associationId: string;
+}, {
+    conversationId: string;
+    associationId: string;
+}, import("@reduxjs/toolkit").AsyncThunkConfig>;
+export declare const dropPendingAttachment: import("@reduxjs/toolkit").ActionCreatorWithPayload<{
+    conversationId: string;
+    key: string;
+}, "conversationAttachments/dropPendingAttachment">, clearAttachmentWriteError: import("@reduxjs/toolkit").ActionCreatorWithPayload<{
+    conversationId: string;
+}, "conversationAttachments/clearAttachmentWriteError">, mergePendingAttachments: import("@reduxjs/toolkit").ActionCreatorWithPayload<{
+    conversationId: string;
+    picks: PendingAttachment[];
+}, "conversationAttachments/mergePendingAttachments">, syncHandoffPendingAttachments: import("@reduxjs/toolkit").ActionCreatorWithPayload<{
+    conversationId: string;
+    picks: PendingAttachment[];
+}, "conversationAttachments/syncHandoffPendingAttachments">, forgetConversationAttachments: import("@reduxjs/toolkit").ActionCreatorWithPayload<string, "conversationAttachments/forgetConversationAttachments">;
+declare const _default: import("redux").Reducer<AttachmentsSliceState>;
+export default _default;
+interface StateWithAttachments {
+    conversationAttachments: AttachmentsSliceState;
+}
+export declare const selectConversationAttachmentsEntry: (conversationId: string) => (state: StateWithAttachments) => ConversationAttachmentsEntry;

package/dist/agents/connectors/attachments.slice.js

@@ -0,0 +1,266 @@
+import {
+  createSlice,
+  createAsyncThunk
+} from "@reduxjs/toolkit";
+import {
+  attachmentKey
+} from "./attachable-resources.js";
+import {
+  attachConversationResource,
+  detachConversationResource,
+  fetchConversationAttachments
+} from "../../host/ui-slots.js";
+const initialState = { byConversationId: {} };
+const EMPTY_ATTACHMENTS_ENTRY = {
+  rows: [],
+  pending: [],
+  status: "idle",
+  error: null,
+  busyKeys: [],
+  writeError: null,
+  handoffInheritedKeys: [],
+  handoffRemovedKeys: []
+};
+function entryFor(state, conversationId) {
+  const existing = state.byConversationId[conversationId];
+  if (existing) return existing;
+  const created = {
+    ...EMPTY_ATTACHMENTS_ENTRY,
+    rows: [],
+    pending: [],
+    busyKeys: [],
+    handoffInheritedKeys: [],
+    handoffRemovedKeys: []
+  };
+  state.byConversationId[conversationId] = created;
+  return created;
+}
+function messageOf(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+const loadConversationAttachments = createAsyncThunk(
+  "conversationAttachments/load",
+  async ({ conversationId }) => ({
+    conversationId,
+    rows: await fetchConversationAttachments(conversationId)
+  })
+);
+const attachResource = createAsyncThunk(
+  "conversationAttachments/attach",
+  async ({
+    conversationId,
+    pick
+  }) => {
+    const row = await attachConversationResource(conversationId, pick);
+    return { conversationId, pick, row };
+  }
+);
+const flushPendingAttachments = createAsyncThunk(
+  "conversationAttachments/flushPending",
+  async ({ conversationId }, { getState }) => {
+    const state = getState();
+    const pending = state.conversationAttachments.byConversationId[conversationId]?.pending ?? [];
+    const landed = [];
+    const failed = [];
+    for (const pick of pending) {
+      try {
+        landed.push(await attachConversationResource(conversationId, pick));
+      } catch (error) {
+        failed.push({ pick, error: messageOf(error) });
+      }
+    }
+    return { conversationId, landed, failed };
+  }
+);
+const detachResource = createAsyncThunk(
+  "conversationAttachments/detach",
+  async ({
+    conversationId,
+    associationId
+  }) => {
+    await detachConversationResource(conversationId, associationId);
+    return { conversationId, associationId };
+  }
+);
+const attachmentsSlice = createSlice({
+  name: "conversationAttachments",
+  initialState,
+  reducers: {
+    /** Remove a pick that never reached the server. */
+    dropPendingAttachment(state, action) {
+      const entry = entryFor(state, action.payload.conversationId);
+      entry.pending = entry.pending.filter(
+        (pick) => attachmentKey(pick) !== action.payload.key
+      );
+      if (entry.handoffInheritedKeys.includes(action.payload.key) && !entry.handoffRemovedKeys.includes(action.payload.key)) {
+        entry.handoffRemovedKeys.push(action.payload.key);
+      }
+    },
+    /** Clear a write failure the user has read. */
+    clearAttachmentWriteError(state, action) {
+      entryFor(state, action.payload.conversationId).writeError = null;
+    },
+    /** Copy selections as pending: association ids belong to the old chat. */
+    mergePendingAttachments(state, action) {
+      const entry = entryFor(state, action.payload.conversationId);
+      for (const pick of action.payload.picks) {
+        const key = attachmentKey(pick);
+        if (!entry.handoffInheritedKeys.includes(key)) {
+          entry.handoffInheritedKeys.push(key);
+        }
+        if (!entry.pending.some(
+          (candidate) => attachmentKey(candidate) === attachmentKey(pick)
+        ) && !entry.rows.some(
+          (candidate) => attachmentKey(candidate) === attachmentKey(pick)
+        )) {
+          entry.pending.push(pick);
+        }
+      }
+    },
+    /** Reconcile only inherited pending picks; destination-local picks stay. */
+    syncHandoffPendingAttachments(state, action) {
+      const entry = entryFor(state, action.payload.conversationId);
+      const nextByKey = new Map(
+        action.payload.picks.filter(
+          (pick) => !entry.handoffRemovedKeys.includes(attachmentKey(pick))
+        ).map((pick) => [attachmentKey(pick), pick])
+      );
+      const inherited = new Set(entry.handoffInheritedKeys);
+      entry.pending = entry.pending.filter((pick) => {
+        const key = attachmentKey(pick);
+        return !inherited.has(key) || nextByKey.has(key);
+      });
+      for (const [key, pick] of nextByKey) {
+        if (!entry.pending.some(
+          (candidate) => attachmentKey(candidate) === key
+        ) && !entry.rows.some((candidate) => attachmentKey(candidate) === key)) {
+          entry.pending.push(pick);
+        }
+      }
+      entry.handoffInheritedKeys = Array.from(nextByKey.keys());
+    },
+    /** Forget a conversation entirely (instance destroyed). */
+    forgetConversationAttachments(state, action) {
+      delete state.byConversationId[action.payload];
+    }
+  },
+  extraReducers: (builder) => {
+    builder.addCase(loadConversationAttachments.pending, (state, action) => {
+      const entry = entryFor(state, action.meta.arg.conversationId);
+      entry.status = "loading";
+      entry.error = null;
+    }).addCase(loadConversationAttachments.fulfilled, (state, action) => {
+      const entry = entryFor(state, action.payload.conversationId);
+      entry.rows = action.payload.rows;
+      entry.status = "succeeded";
+      entry.error = null;
+      const landed = new Set(
+        action.payload.rows.map((row) => attachmentKey(row))
+      );
+      entry.pending = entry.pending.filter(
+        (pick) => !landed.has(attachmentKey(pick))
+      );
+    }).addCase(loadConversationAttachments.rejected, (state, action) => {
+      const entry = entryFor(state, action.meta.arg.conversationId);
+      entry.status = "failed";
+      entry.error = action.error.message ?? "Could not read this chat's attachments.";
+    }).addCase(attachResource.pending, (state, action) => {
+      const entry = entryFor(state, action.meta.arg.conversationId);
+      const key = attachmentKey(action.meta.arg.pick);
+      if (!entry.busyKeys.includes(key)) entry.busyKeys.push(key);
+      entry.writeError = null;
+    }).addCase(attachResource.fulfilled, (state, action) => {
+      const entry = entryFor(state, action.payload.conversationId);
+      const key = attachmentKey(action.payload.pick);
+      entry.busyKeys = entry.busyKeys.filter((busy) => busy !== key);
+      const row = action.payload.row;
+      const existing = entry.rows.findIndex(
+        (candidate) => attachmentKey(candidate) === attachmentKey(row)
+      );
+      if (existing >= 0) entry.rows[existing] = row;
+      else entry.rows.push(row);
+      entry.pending = entry.pending.filter(
+        (pick) => attachmentKey(pick) !== key
+      );
+    }).addCase(attachResource.rejected, (state, action) => {
+      const entry = entryFor(state, action.meta.arg.conversationId);
+      const key = attachmentKey(action.meta.arg.pick);
+      entry.busyKeys = entry.busyKeys.filter((busy) => busy !== key);
+      entry.writeError = action.error.message ?? `${action.meta.arg.pick.display_name} could not be attached.`;
+    }).addCase(flushPendingAttachments.fulfilled, (state, action) => {
+      const entry = entryFor(state, action.payload.conversationId);
+      for (const row of action.payload.landed) {
+        const key = attachmentKey(row);
+        if (!entry.rows.some((candidate) => attachmentKey(candidate) === key)) {
+          entry.rows.push(row);
+        }
+      }
+      const stillPending = new Set(
+        action.payload.failed.map(({ pick }) => attachmentKey(pick))
+      );
+      entry.pending = entry.pending.filter(
+        (pick) => stillPending.has(attachmentKey(pick))
+      );
+      entry.writeError = action.payload.failed.length > 0 ? `${action.payload.failed.length} attachment${action.payload.failed.length === 1 ? "" : "s"} could not be carried over: ${action.payload.failed[0].error}` : null;
+    }).addCase(flushPendingAttachments.rejected, (state, action) => {
+      const entry = entryFor(state, action.meta.arg.conversationId);
+      entry.writeError = action.error.message ?? "The attachments you picked before this chat existed could not be carried over.";
+    }).addCase(detachResource.pending, (state, action) => {
+      const entry = entryFor(state, action.meta.arg.conversationId);
+      const row = entry.rows.find(
+        (candidate) => candidate.association_id === action.meta.arg.associationId
+      );
+      if (row && !entry.busyKeys.includes(attachmentKey(row))) {
+        entry.busyKeys.push(attachmentKey(row));
+      }
+      entry.writeError = null;
+    }).addCase(detachResource.fulfilled, (state, action) => {
+      const entry = entryFor(state, action.payload.conversationId);
+      const row = entry.rows.find(
+        (candidate) => candidate.association_id === action.payload.associationId
+      );
+      entry.rows = entry.rows.filter(
+        (candidate) => candidate.association_id !== action.payload.associationId
+      );
+      if (row) {
+        entry.busyKeys = entry.busyKeys.filter(
+          (busy) => busy !== attachmentKey(row)
+        );
+      }
+    }).addCase(detachResource.rejected, (state, action) => {
+      const entry = entryFor(state, action.meta.arg.conversationId);
+      const row = entry.rows.find(
+        (candidate) => candidate.association_id === action.meta.arg.associationId
+      );
+      if (row) {
+        entry.busyKeys = entry.busyKeys.filter(
+          (busy) => busy !== attachmentKey(row)
+        );
+      }
+      entry.writeError = action.error.message ?? "That attachment could not be removed.";
+    });
+  }
+});
+const {
+  dropPendingAttachment,
+  clearAttachmentWriteError,
+  mergePendingAttachments,
+  syncHandoffPendingAttachments,
+  forgetConversationAttachments
+} = attachmentsSlice.actions;
+var attachments_slice_default = attachmentsSlice.reducer;
+const selectConversationAttachmentsEntry = (conversationId) => (state) => state.conversationAttachments.byConversationId[conversationId] ?? EMPTY_ATTACHMENTS_ENTRY;
+export {
+  EMPTY_ATTACHMENTS_ENTRY,
+  attachResource,
+  clearAttachmentWriteError,
+  attachments_slice_default as default,
+  detachResource,
+  dropPendingAttachment,
+  flushPendingAttachments,
+  forgetConversationAttachments,
+  loadConversationAttachments,
+  mergePendingAttachments,
+  selectConversationAttachmentsEntry,
+  syncHandoffPendingAttachments
+};

package/dist/agents/connectors/chat-connections.d.ts

@@ -0,0 +1,76 @@
+/**
+ * What THIS chat is actually wired to — the list the composer shows.
+ *
+ * Arman, 2026-09-14: "I don't see an MCP chip."
+ *
+ * He was right, and the reason was placement, not honesty. The honest
+ * three-state chips (Connected / Needs re-auth / Not connected) shipped into
+ * the Tools picker, which is two clicks and a three-row scroll box away. The
+ * one line that DOES sit under the composer — `ChatConnectorStrip` — draws a
+ * randomized three-of-the-catalog suggestion bag ("connect these"), so it can
+ * (and on a live check did) show Nuxt / Clerk / Notion while this chat's own
+ * servers, and a server attached seconds earlier, appear nowhere.
+ *
+ * The champion bar (Claude.ai and ChatGPT connectors, Cursor's MCP indicator):
+ * what the conversation can reach is legible from the composer without opening
+ * anything, and one click away from the place that changes it.
+ *
+ * This module is that list's ONE decision, kept pure so a test can prove it:
+ * a server appears only because this chat is actually wired to it, its state
+ * is the truthful one, and problems sort to the front where they get seen.
+ */
+import type { McpConnectionState } from "./connection-state.js";
+import type { RunMcpAttachment } from "./run-attachments.js";
+import { type AttachableResource, type ChatConnectionKind } from "./attachable-resources.js";
+/** One catalog server as the caller already knows it. */
+export interface ChatConnectionCatalogEntry {
+    slug: string;
+    name: string;
+    state: McpConnectionState;
+    reason: string | null;
+    /**
+     * What this connection lets a person CHOOSE from. Empty (or absent) means a
+     * pure MCP connection. Straight from the server's availability payload —
+     * never inferred from the slug.
+     */
+    attachable?: readonly AttachableResource[] | null;
+}
+/** One server this conversation is wired to, with the truth about it. */
+export interface ChatConnection {
+    slug: string;
+    /** The server's display name; falls back to the slug when uncatalogued. */
+    name: string;
+    /** Truthful state: the run's own answer when it has one, else the catalog. */
+    state: McpConnectionState;
+    reason: string | null;
+    /** Why it is in this chat: the agent's saved definition, or this run. */
+    origin: "agent" | "run";
+    /** What the last run actually did with it, when the run said. */
+    runAttachment: RunMcpAttachment | undefined;
+    /**
+     * `plain` — the connection is the whole story (a pure MCP server).
+     * `attachable` — the connection is also a door to a chooser, and the chip
+     * owes the person that door plus a count of what they have chosen
+     * (Arman, 2026-09-15).
+     */
+    kind: ChatConnectionKind;
+    /** The resource kinds behind that door, in the provider's own words. */
+    attachable: AttachableResource[];
+}
+export interface SelectChatConnectionsInput {
+    /** Slugs on the agent's saved definition — they ride every run. */
+    agentServerSlugs: readonly string[] | undefined;
+    /** Slugs added to THIS conversation only (`addedMcpServers`). */
+    addedServerSlugs: readonly string[] | undefined;
+    /** The catalog, already carrying each server's one truthful state. */
+    catalog: readonly ChatConnectionCatalogEntry[];
+    /** What the latest run reported per slug, indexed by slug. */
+    runAttachments: Readonly<Record<string, RunMcpAttachment>>;
+}
+/**
+ * The servers this conversation is wired to, worst state first.
+ *
+ * A server the user merely *could* connect is never in this list — that is the
+ * suggestion strip's job, and conflating the two is what hid the real ones.
+ */
+export declare function selectChatConnections({ agentServerSlugs, addedServerSlugs, catalog, runAttachments, }: SelectChatConnectionsInput): ChatConnection[];

package/dist/agents/connectors/chat-connections.js

@@ -0,0 +1,53 @@
+import {
+  chatConnectionKind,
+  normalizeAttachable
+} from "./attachable-resources.js";
+const STATE_ORDER = {
+  needs_reauth: 0,
+  not_connected: 1,
+  connected: 2
+};
+function selectChatConnections({
+  agentServerSlugs,
+  addedServerSlugs,
+  catalog,
+  runAttachments
+}) {
+  const bySlug = new Map(catalog.map((entry) => [entry.slug, entry]));
+  const origins = /* @__PURE__ */ new Map();
+  for (const slug of agentServerSlugs ?? []) {
+    if (slug) origins.set(slug, "agent");
+  }
+  for (const slug of addedServerSlugs ?? []) {
+    if (slug && !origins.has(slug)) origins.set(slug, "run");
+  }
+  for (const slug of Object.keys(runAttachments)) {
+    if (slug && !origins.has(slug)) origins.set(slug, "run");
+  }
+  const connections = [...origins.entries()].map(
+    ([slug, origin]) => {
+      const entry = bySlug.get(slug);
+      const runAttachment = runAttachments[slug];
+      const attachable = normalizeAttachable(entry?.attachable);
+      return {
+        slug,
+        name: entry?.name ?? slug,
+        // The run's own answer wins: only it knows what the model was handed.
+        state: runAttachment?.state ?? entry?.state ?? "not_connected",
+        reason: runAttachment?.reason ?? entry?.reason ?? null,
+        origin,
+        runAttachment,
+        kind: chatConnectionKind(attachable),
+        attachable
+      };
+    }
+  );
+  return connections.sort((a, b) => {
+    const byState = STATE_ORDER[a.state] - STATE_ORDER[b.state];
+    if (byState !== 0) return byState;
+    return a.name.localeCompare(b.name);
+  });
+}
+export {
+  selectChatConnections
+};

package/dist/agents/connectors/connection-state.d.ts

@@ -0,0 +1,79 @@
+/**
+ * The ONE truthful answer to "is this MCP server usable right now?".
+ *
+ * Arman, 2026-09-13: "the user is also blind as to the MCPs that are attached
+ * … the ui lies as well since I see a checkmark for git but don't actually
+ * have the mcp connected according to the agent."
+ *
+ * Every indicator in the chat hierarchy (the run tool picker, the agent tools
+ * manager, the connector strip) used to decide from `tool.mcp_user_conn.status`
+ * alone. That single field lies in three separate ways:
+ *
+ *  1. a row still saying `connected` whose `token_expires_at` passed days ago;
+ *  2. `refresh_failed` / `error`, which needs the user, not a retry;
+ *  3. slug `github`, whose bearer comes from the FIRST-PARTY GitHub App
+ *     connection (`users.integration_connections`) — its MCP connection row
+ *     says nothing at all about whether GitHub works.
+ *
+ * aidream owns the authoritative machine (`describe_mcp_availability`, served
+ * by `GET /api/mcp-connections/availability`) because only the server can see
+ * whether a stored refresh token exists. This module is the same machine's
+ * catalog-only form: it is what a surface renders before (or without) that
+ * answer, and the server's answer always wins when it is present.
+ *
+ * NO hardcoded provider list lives here. GitHub is not special-cased by slug:
+ * a first-party integration status is passed in by whoever holds it, keyed by
+ * the server's own slug.
+ */
+import type { McpCatalogEntry } from "../types/mcp.types.js";
+import type { components } from "@ai-matrx/agents/generated/api-types";
+/** What a person may be told about one MCP server. Exactly three states. */
+export type McpConnectionState = 
+/** Usable on the next run: no auth needed, token valid, or renewable. */
+"connected"
+/** A connection exists but only the user can restore it. */
+ | "needs_reauth"
+/** Nothing usable on file — the one-click offer. */
+ | "not_connected";
+export interface McpConnectionTruth {
+    state: McpConnectionState;
+    /** Plain-English why, for every state but a plain healthy `connected`. */
+    reason: string | null;
+    /** `server` when aidream answered; `catalog` when derived from DB rows. */
+    source: "server" | "catalog";
+}
+/** The server's per-user answer (`GET /api/mcp-connections/availability`). */
+export type McpAvailability = components["schemas"]["McpAvailability"];
+/**
+ * A first-party integration connection's status, as
+ * `users.integration_connections.status` records it. Supplied by the surface
+ * that already reads those rows; never fetched here.
+ */
+export type FirstPartyStatus = string | null | undefined;
+export interface DeriveOptions {
+    /** aidream's answer for this slug. Authoritative when present. */
+    availability?: McpAvailability | null;
+    /**
+     * The status of a first-party integration connection carrying this server's
+     * bearer, when one exists (GitHub today). `null` means "this server has a
+     * first-party path and the user has no connection on it".
+     */
+    firstPartyStatus?: FirstPartyStatus;
+    /** True when this server's bearer comes from a first-party connection. */
+    hasFirstPartyPath?: boolean;
+    /** Injected for tests. */
+    now?: Date;
+}
+/**
+ * Derive the truthful state for one catalog entry.
+ *
+ * Order of authority: a loaded first-party connection (when the server has
+ * one) → aidream's answer → the server's own auth strategy → the MCP
+ * connection row. GitHub's bearer and vault state belong to that first-party
+ * connection, so a stale MCP availability result cannot overrule it.
+ */
+export declare function deriveMcpConnectionState(entry: Pick<McpCatalogEntry, "slug" | "authStrategy" | "connectionStatus" | "tokenExpiresAt"> & {
+    serverStatus?: McpCatalogEntry["serverStatus"];
+}, options?: DeriveOptions): McpConnectionTruth;
+/** Short label for a state. One vocabulary across every surface. */
+export declare const MCP_STATE_LABEL: Record<McpConnectionState, string>;