@ai-matrx/agents 0.7.1 → 0.9.0

package/dist/catalog/index.d.ts

@@ -1,521 +1,5 @@
-/**
- * `@ai-matrx/agents/catalog` — the row shape and the per-consumer view state.
- *
- * `AgentSummary` is the 19-column row `agx_get_list_full()` returns, camelCased.
- * It is deliberately NOT the editable agent record: dirty tracking, undo,
- * messages, tools and `_fetchStatus` stay in whichever host owns the editor.
- * A list row is a list row.
- *
- * The view-state types are a VERBATIM port of matrx-frontend
- * `features/agents/redux/agent-consumers/slice.ts` — only the coupling seam
- * inverts (Redux reducers become store actions in `./store`).
- */
-/**
- * A branded agent id. Every id that reaches `onSelect` is one of these:
- * either a `agent.definition` UUID, or the `mandate:<key>` reference a
- * default row carries (byte-identical to the ref shape matrx-extend
- * `src/lib/mandates.ts` and matrx-local `desktop/src/lib/mandates.ts`
- * already hand back to their hosts).
- *
- * 🚨 The brand is a STRING LITERAL, never `unique symbol`. This package emits
- * `./catalog` and `./catalog/react` as two separate bundles, so each `.d.ts`
- * carries its own copy of these declarations. A `unique symbol` brand is
- * NOMINAL: two copies of it are unrelated types, so `createAgentCatalog()`
- * from `./catalog` was not assignable to `<AgentCatalogProvider catalog=…>`
- * from `./catalog/react` — the exact two-import wiring the README, the
- * CHANGELOG and every consumer use. A literal brand is structural, so the two
- * copies unify, while a bare `string` still cannot be passed where an
- * `AgentId` is required (which is the whole point of branding). Any future
- * brand in this package follows the same rule.
- */
-type AgentId = string & {
-    readonly __agentId: "ai-matrx.agent-id";
-};
-/** Brand a raw string as an `AgentId`. */
-declare function asAgentId(value: string): AgentId;
-/** The `mandate:<key>` ref shape every client already speaks. */
-declare function mandateAgentId(mandateKey: string): AgentId;
-/** True when an id is a mandate default row rather than a stored agent. */
-declare function isMandateAgentId(id: string): boolean;
-/** `agent_type` verbatim. Only `builtin` changes how a row is grouped. */
-type AgentCatalogAgentType = "user" | "builtin";
-/**
- * `access_level` verbatim from `agx_get_list_full`. Widened over the raw
- * string because it is a DB-owned vocabulary: an unknown level renders as
- * itself rather than being coerced into a wrong one.
- */
-type AgentAccessLevel = "owner" | "admin" | "editor" | "viewer" | "system" | (string & {});
-/**
- * One `agx_get_list_full()` row, camelCased. Nineteen columns, no more:
- * anything richer needs a different read and is a different type.
- */
-interface AgentSummary {
-    id: AgentId;
-    name: string | null;
-    description: string | null;
-    category: string | null;
-    tags: string[];
-    agentType: AgentCatalogAgentType;
-    modelId: string | null;
-    isActive: boolean;
-    isArchived: boolean;
-    isFavorite: boolean;
-    createdBy: string | null;
-    organizationId: string | null;
-    taskId: string | null;
-    sourceAgentId: string | null;
-    createdAt: string | null;
-    updatedAt: string | null;
-    isOwner: boolean | null;
-    accessLevel: AgentAccessLevel | null;
-    sharedByEmail: string | null;
-    /**
-     * Set only on a mandate default row — the key it resolved through, so a
-     * host can tell "the default" from a stored agent without parsing the id.
-     */
-    mandateKey?: string;
-}
-type AgentSortOption = "updated-desc" | "created-desc" | "name-asc" | "name-desc" | "category-asc";
-/** Which ownership tab is active in the agent list. */
-type AgentTab = "mine" | "shared" | "all" | "system";
-/** Favorite filter. */
-type AgentFavFilter = "all" | "yes" | "no";
-/** Archive filter. */
-type AgentArchFilter = "active" | "archived" | "both";
-/**
- * Access level filter.
- * 'any'    = no restriction (default).
- * 'owned'  = only agents the user owns (isOwner = true).
- * 'shared' = only agents shared with the user (isOwner = false).
- * 'editable' = owner + admin + editor.
- */
-type AgentAccessFilter = "any" | "owned" | "shared" | "editable";
-/** Sentinel meaning "include uncategorized / untagged" items. */
-declare const AGENT_NONE_SENTINEL = "__none__";
-interface AgentConsumerState {
-    tab: AgentTab;
-    sortBy: AgentSortOption;
-    searchTerm: string;
-    /** INCLUSION model: empty = show all; non-empty = only matching. */
-    includedCats: string[];
-    /** INCLUSION model: empty = show all; non-empty = only matching. */
-    includedTags: string[];
-    favFilter: AgentFavFilter;
-    archFilter: AgentArchFilter;
-    accessFilter: AgentAccessFilter;
-    favoritesFirst: boolean;
-    /** Current page for owned-agent list items (after the card section). */
-    listPage: number;
-    /** Current page for shared-agent list items. */
-    sharedPage: number;
-    /**
-     * Ids returned by the last server-side search (`agx_search`), in server rank
-     * order. Additive: an agent in this list survives the search filter even
-     * when the local scorer gives it 0.
-     *
-     * That is load-bearing for tier 2. A deep search matches an agent's prompt
-     * content, which the client never loads — so the local scorer cannot see it.
-     * Without this list the server would return prompt matches and the UI would
-     * immediately filter them back out.
-     *
-     * Server-only matches sort BELOW every locally-scored match, in server rank
-     * order, so obvious matches always come first.
-     */
-    serverMatchedIds: string[];
-    /** True while a server search is in flight — drives the search spinner. */
-    isServerSearching: boolean;
-    /** Tier 2: also search agent prompt content. Opt-in, per consumer. */
-    deepSearch: boolean;
-}
-declare const DEFAULT_AGENT_CONSUMER_STATE: AgentConsumerState;
-/** The subset of consumer state a caller may patch (paging is derived). */
-type AgentConsumerPatch = Partial<Omit<AgentConsumerState, "listPage" | "sharedPage">>;
-/**
- * Thrown by `createAgentCatalog` when a REQUIRED port is missing or an
- * optional feature was asked for without the port it needs. Never a warning,
- * never a degraded catalog: a picker that cannot read is not a picker.
- */
-declare class AgentCatalogConfigError extends Error {
-    readonly name = "AgentCatalogConfigError";
-    /** Machine code, for a host that routes config failures. */
-    readonly code: string;
-    /** What the host must do, in a sentence a person can act on. */
-    readonly remedy: string;
-    constructor(args: {
-        code: string;
-        message: string;
-        remedy: string;
-    });
-}
-
-/**
- * `@ai-matrx/agents/catalog` — THE PORTS.
- *
- * Two are required (`client`, `identity`); every other one ships a working
- * default with a DOCUMENTED degradation, per THE ALL-INCLUSIVE LAW. A host
- * injects identity and a Supabase client and nothing else; the picker's only
- * contract back to the host is `onSelect(agentId)`.
- *
- * React appears nowhere in this file — it is import-inert and legal in any
- * graph, server components included.
- */
-
-/** A PostgREST error, structurally. */
-interface PgErrorLike {
-    message: string;
-    code?: string;
-    details?: string | null;
-    hint?: string | null;
-}
-/** What every supabase-js call resolves to, structurally. */
-interface PgResultLike {
-    data: unknown;
-    error: PgErrorLike | null;
-    count?: number | null;
-}
-/**
- * The thenable builder supabase-js returns from `.rpc()`. `range` is what
- * makes a COMPLETE list read possible (`readAllRows`); `order` is what makes
- * that paging stable. Both are the real builder's own methods — this is a
- * structural subset, never a re-implementation.
- */
-interface AgentCatalogRpcCall extends PromiseLike<PgResultLike> {
-    range(from: number, to: number): PromiseLike<PgResultLike>;
-    order(column: string, options?: {
-        ascending?: boolean;
-    }): AgentCatalogRpcCall;
-}
-/** The one write this package performs: `agent.definition.is_favorite`. */
-interface AgentCatalogTableQuery {
-    update(patch: Record<string, unknown>): {
-        eq(column: string, value: string): PromiseLike<{
-            data?: unknown;
-            error: PgErrorLike | null;
-        }>;
-    };
-}
-/**
- * REQUIRED. A structural subset of `SupabaseClient` — anything that can answer
- * `agx_get_list_full`, `agx_search`, `agx_resolve_agent_address` and write one
- * column on `agent.definition`. A real supabase-js client satisfies it as-is.
- *
- * Absent → `createAgentCatalog` throws `AgentCatalogConfigError`. There is no
- * degraded mode: the package IS the catalogue read.
- */
-interface AgentCatalogClient {
-    rpc(fn: string, args?: Record<string, unknown>, options?: {
-        count?: "exact" | "planned" | "estimated";
-    }): AgentCatalogRpcCall;
-    schema(name: string): {
-        from(table: string): AgentCatalogTableQuery;
-    };
-}
-/**
- * REQUIRED. Who is asking. Needed for the "zero owned agents → open on the
- * public tab" heuristic and for the favorite write.
- *
- * `requireUserId` THROWS when there is no session — never a silent anonymous
- * read. The catalog catches that throw in exactly ONE place (the tab-default
- * heuristic, where a signed-out visitor legitimately lands on the public
- * catalogue) and reports it to the `errorSink` the first time; every other
- * caller lets it propagate.
- */
-interface AgentCatalogIdentity {
-    requireUserId(): string;
-}
-/**
- * Every degraded path, every failed read, every drift detection reports here.
- * DEFAULT: a tagged `console.error` that announces ONCE that no sink is bound
- * and names the remedy.
- */
-type AgentCatalogErrorSink = (event: {
-    code: string;
-    message: string;
-    context?: object;
-}) => void;
-/**
- * The drift scream's second channel. DEFAULT: none — and that is safe
- * ONLY because the in-picker persistent banner is the primary scream and
- * always renders. A drift is never console-only.
- */
-type AgentCatalogNotifier = (event: {
-    level: "warning" | "error";
-    title: string;
-    message: string;
-}) => void;
-/**
- * First-paint cache for resolved default rows. DEFAULT: `localStorage` when
- * present, else an in-memory map (so SSR and a Chrome service worker both
- * work). Absent storage degrades to "no first paint of the default row until
- * the mandate resolves" — never a wrong name on screen.
- */
-interface AgentCatalogStorage {
-    getItem(key: string): string | null;
-    setItem(key: string, value: string): void;
-    removeItem(key: string): void;
-}
-/** Every user-visible string the picker renders, overridable per host. */
-interface AgentCatalogLabels {
-    /** User-facing label for the `system` ownership tab. */
-    publicTab: string;
-    /**
-     * Badge label on a builtin row. Default `"system"` — the string
-     * `AgentRow` actually rendered in matrx-frontend. (The frontend also
-     * declared `AGENT_PUBLIC_BADGE_LABEL = "Public"` for this badge and NOTHING
-     * ever read it — a constant that named the badge without being the badge.
-     * Recorded in the CHANGELOG and dropped rather than ported.)
-     */
-    systemBadge: string;
-    searchPlaceholder: string;
-    currentAgentHeading: string;
-    emptyDefault: string;
-    emptyShared: string;
-    emptySystem: string;
-    loading: string;
-    triggerFallback: string;
-    triggerResolving: string;
-    triggerUnnameable: string;
-    hoverHint: string;
-}
-declare const DEFAULT_AGENT_CATALOG_LABELS: AgentCatalogLabels;
-interface AgentCatalogConfig {
-    /** REQUIRED — the Supabase client. */
-    client: AgentCatalogClient;
-    /** REQUIRED — who is asking. */
-    identity: AgentCatalogIdentity;
-    /**
-     * The catalog's registry key on `globalThis`. Two `createAgentCatalog`
-     * calls with the same id are the same catalog (and the second one screams
-     * through the errorSink before replacing the first). Default `"default"`.
-     */
-    catalogId?: string;
-    /** OPTIONAL — see `AgentCatalogErrorSink`. */
-    errorSink?: AgentCatalogErrorSink;
-    /** OPTIONAL — see `AgentCatalogNotifier`. */
-    notifier?: AgentCatalogNotifier;
-    /** OPTIONAL — see `AgentCatalogStorage`. */
-    storage?: AgentCatalogStorage;
-    /**
-     * OPTIONAL — the package's own `MatrxTransport` (`createMatrxTransport`
-     * from `@ai-matrx/agents/matrx`). REQUIRED the moment any picker instance
-     * passes a `defaultMandateKey`: THE PLATFORM RULE D-R1 says clients never
-     * walk the mandate ladder, so the default row can only be resolved through
-     * the aidream door `GET /mandates/{mandate_key}/resolution`. A
-     * `defaultMandateKey` with no transport throws `AgentCatalogConfigError`.
-     */
-    transport?: AgentCatalogTransport;
-    /** OPTIONAL — label overrides. */
-    labels?: Partial<AgentCatalogLabels>;
-}
-/**
- * The transport seam, structurally identical to `MatrxTransport` from
- * `@ai-matrx/agents/matrx` (declared structurally so `./catalog` never
- * imports the transport module and stays import-inert).
- */
-interface AgentCatalogTransport {
-    fetch(path: string, init: {
-        method: "GET" | "POST";
-        headers: Record<string, string>;
-        body?: string;
-        signal?: AbortSignal;
-    }): Promise<Response>;
-}
-/**
- * Where a row's href goes when someone cmd-clicks it, and where `navigateTo`
- * lands. DEFAULT: `window.location.assign` (so cmd-click and ordinary
- * navigation both work with no host wiring at all).
- */
-type AgentCatalogNavigate = (href: string) => void;
-/** Resolve a per-row href. DEFAULT: `/agents/go/<id>` — the always-valid door. */
-type AgentCatalogResolveHref = (agent: AgentSummary) => string;
-/**
- * The sneak-peek affordance. Absent → the affordance is HIDDEN, never a dead
- * button (nothing fails silently, and nothing looks alive when it is not).
- */
-type AgentCatalogOpenPeek = (agent: AgentSummary) => void;
-
-/**
- * catalog/default-row-types.ts — @ai-matrx/agents/catalog
- *
- * Split out of `default-row.ts` so `global-state.ts` can name the cached
- * shape without importing the resolver (and its transport work) — the same
- * split-out reflex C8 asks for, at module scale.
- */
-
-/** The wire shape of `GET /mandates/{mandate_key}/resolution`, narrowed. */
-interface MandateResolutionVerdict {
-    mandateKey: string;
-    holderType: string;
-    /** The executable id. `null` for a workflow Holder — a picker cannot run one. */
-    agentId: string | null;
-    isVersion: boolean;
-    /** Always the `agent.definition` id, even when `agentId` is a version. */
-    definitionAgentId: string | null;
-    /** Which precedence layer answered. Shown so a person can see WHY. */
-    provenance: string;
-}
-/** A resolved default row, cached for first paint and compared for drift. */
-interface ResolvedDefaultRow {
-    mandateKey: string;
-    /** The `agent.definition` id the mandate resolved to. */
-    holderId: string;
-    /** The holder's REAL name, read from the catalogue — never hardcoded. */
-    holderName: string;
-    holderDescription: string | null;
-    provenance: string;
-    /** Epoch ms of this resolution. */
-    at: number;
-}
-/** What the picker renders and what it screams, together. */
-interface DefaultRowState {
-    mandateKey: string;
-    /** The row to render at the top of the list. `null` until resolved. */
-    row: AgentSummary | null;
-    /** The last live resolution, or the cached one before the live answer lands. */
-    resolved: ResolvedDefaultRow | null;
-    /** True while the resolution is in flight. */
-    loading: boolean;
-    /**
-     * 🚨 THE DRIFT SCREAM. Set when the cached first-paint row and the LIVE
-     * resolution disagree on holder id or holder name. Rendered as a persistent
-     * in-picker banner AND sent to the `notifier` port — never console-only.
-     */
-    drift: string | null;
-    /** Set when the mandate could not be resolved at all. Loud, with a remedy. */
-    error: string | null;
-}
-
-/**
- * catalog/schema.ts — @ai-matrx/agents/catalog
- *
- * THE DEMANDED SCHEMA PROBE (the `@ai-matrx/associations` `assertDemandedSchema`
- * precedent). It proves that the database a host pointed this catalog at can
- * actually answer the three functions the picker demands.
- *
- * 🚨 IT MUST BE ABLE TO FAIL. A probe whose green result is unconditional
- * proves nothing, so `selfTest: true` also probes a fabricated function name
- * and REQUIRES it to come back missing. `catalog/__tests__/schema.test.ts`
- * runs the whole probe against a client whose `rpc` answers PostgreSQL 42883
- * (`undefined_function`, which PostgREST surfaces as PGRST202) and asserts the
- * loud error.
- */
-
-interface AgentCatalogSchemaReport {
-    ok: boolean;
-    /** Demanded functions the database cannot answer. */
-    missing: string[];
-    /** Functions the probe could not reach (transport/unknown failure). */
-    unreachable: {
-        fn: string;
-        error: unknown;
-    }[];
-    /** Functions that answered (success or any non-missing refusal). */
-    answered: string[];
-    /** True when `agent.definition.is_favorite` is writable by this caller. */
-    favoriteWritable: boolean | null;
-}
-interface AssertAgentCatalogSchemaOptions {
-    /**
-     * Also probe a fabricated function name and REQUIRE it to come back
-     * missing — proves this probe can fail.
-     */
-    selfTest?: boolean;
-    /** Return the report instead of throwing. The self-test failure ALWAYS throws. */
-    throwOnViolation?: boolean;
-    /**
-     * Also probe the ONE write (`agent.definition.is_favorite`) against an
-     * impossible id, so a 42501/permission refusal is seen at boot rather than
-     * on a user's first click. Default: on.
-     */
-    probeWrite?: boolean;
-}
-/**
- * Probe every demanded function. Throws an `Error` naming each missing one
- * (unless `throwOnViolation: false`), and ALWAYS throws when the probe itself
- * cannot be trusted (unreachable database, failed self-test).
- */
-declare function assertAgentCatalogSchema(client: AgentCatalogClient, options?: AssertAgentCatalogSchemaOptions): Promise<AgentCatalogSchemaReport>;
-
-/**
- * catalog/store.ts — @ai-matrx/agents/catalog
- *
- * `createAgentCatalog(config)` — the headless kernel. Everything the picker
- * knows lives here: the row registry, the complete-list read with its
- * session-shared in-flight dedupe and freshness window, the tier-2 server
- * search, the per-consumer view state, the ONE write, and the mandate default
- * row with its drift screamer.
- *
- * The host injects a Supabase client and who the user is. Nothing else.
- *
- * The consumer reducers below are a VERBATIM port of matrx-frontend
- * `features/agents/redux/agent-consumers/slice.ts`; only the seam inverts
- * (a Redux reducer becomes a store method, and Immer's draft mutation becomes
- * an explicit copy so the store can publish a new reference).
- */
-
-type AgentCatalogStatus = "idle" | "loading" | "succeeded" | "failed";
-interface AgentCatalogState {
-    /** Every row, one stable array reference per change (memoization depends on it). */
-    rows: AgentSummary[];
-    byId: Record<string, AgentSummary>;
-    status: AgentCatalogStatus;
-    error: string | null;
-    consumers: Record<string, AgentConsumerState>;
-    /** Keyed by mandate key. */
-    defaultRows: Record<string, DefaultRowState>;
-}
-interface AgentCatalog {
-    readonly catalogId: string;
-    readonly labels: AgentCatalogLabels;
-    readonly errorSink: AgentCatalogErrorSink;
-    readonly notifier: AgentCatalogNotifier | undefined;
-    /** True when this catalog was given a transport and can resolve mandates. */
-    readonly canResolveMandates: boolean;
-    getState(): AgentCatalogState;
-    subscribe(listener: () => void): () => void;
-    getAgent(agentId: string): AgentSummary | undefined;
-    /**
-     * The signed-in user id, or `null` when there is no session. The ONE place
-     * `identity.requireUserId()`'s throw is caught — a signed-out visitor
-     * legitimately lands on the public catalogue — and it is reported to the
-     * errorSink the first time so it is never silent.
-     */
-    getUserIdOrNull(): string | null;
-    /** Load the catalogue if it is not fresh. Safe to call on every mount. */
-    ensureLoaded(options?: {
-        force?: boolean;
-    }): Promise<void>;
-    /** True when the last load is inside the 15-minute TTL. */
-    isFresh(): boolean;
-    /** True when the last load is older than 4 hours (tab-restore threshold). */
-    isStale(): boolean;
-    getConsumer(consumerId: string): AgentConsumerState;
-    registerConsumer(consumerId: string, initial?: AgentConsumerPatch): void;
-    unregisterConsumer(consumerId: string): void;
-    setConsumerFilter(consumerId: string, patch: AgentConsumerPatch): void;
-    setConsumerPage(consumerId: string, which: "list" | "shared", page: number): void;
-    setConsumerServerSearch(consumerId: string, args: {
-        matchedIds?: string[];
-        isSearching?: boolean;
-    }): void;
-    resetConsumerFilters(consumerId: string): void;
-    /** Tier-2 search. Purely additive; merges rows into the registry. */
-    searchServer(query: string, deep?: boolean): Promise<string[]>;
-    /** THE ONE WRITE. Optimistic, rolled back on failure, loud either way. */
-    setFavorite(agentId: string, isFavorite: boolean): Promise<void>;
-    /** Resolve (once) the default row for a mandate key. Idempotent. */
-    ensureDefaultRow(mandateKey: string): void;
-    getDefaultRow(mandateKey: string): DefaultRowState | undefined;
-    /** A person acknowledged the drift banner. The notifier already fired. */
-    dismissDefaultRowDrift(mandateKey: string): void;
-    assertSchema(options?: AssertAgentCatalogSchemaOptions): Promise<AgentCatalogSchemaReport>;
-}
-declare function createAgentCatalog(config: AgentCatalogConfig): AgentCatalog;
-/**
- * The catalog registered under `catalogId`, across loader graphs. Returns
- * `undefined` when none has been created yet — never a silent stub.
- */
-declare function getRegisteredAgentCatalog(catalogId?: string): AgentCatalog | undefined;
+import { A as AgentSummary, a as AgentCatalogClient, b as AgentCatalogTransport, c as AgentCatalogStorageLike, d as AgentCatalogErrorSink, R as ResolvedDefaultRow, e as AgentCatalogStorage, M as MandateResolutionVerdict, f as AgentTab, g as AgentCatalogLabels, h as AgentConsumerState, i as AgentSortOption } from '../orchestra-BWJM2MWP.js';
+export { j as AGENT_NONE_SENTINEL, k as AgentAccessFilter, l as AgentAccessLevel, m as AgentArchFilter, n as AgentCatalog, o as AgentCatalogAgentType, p as AgentCatalogAsyncStorage, q as AgentCatalogConfig, r as AgentCatalogConfigError, s as AgentCatalogIdentity, t as AgentCatalogNavigate, u as AgentCatalogNotifier, v as AgentCatalogOpenPeek, w as AgentCatalogResolveHref, x as AgentCatalogRpcCall, y as AgentCatalogSchemaReport, z as AgentCatalogState, B as AgentCatalogStatus, C as AgentCatalogTableQuery, D as AgentConsumerPatch, E as AgentFavFilter, F as AgentId, G as AssertAgentCatalogSchemaOptions, H as DEFAULT_AGENT_CATALOG_LABELS, I as DEFAULT_AGENT_CONSUMER_STATE, J as DefaultRowState, O as OrchestraBadge, P as PgErrorLike, K as PgResultLike, S as SORT_OPTIONS, L as asAgentId, N as assertAgentCatalogSchema, Q as createAgentCatalog, T as getRegisteredAgentCatalog, U as isMandateAgentId, V as mandateAgentId, W as orchestraDelegatesLine, X as orchestraDepthLine, Y as orchestraLabel, Z as orchestraModeLabel } from '../orchestra-BWJM2MWP.js';
 
 /**
  * catalog/data.ts — @ai-matrx/agents/catalog
@@ -593,9 +77,14 @@ declare function writeAgentFavorite(client: AgentCatalogClient, agentId: string,
  * catalog/rows.ts — @ai-matrx/agents/catalog
  *
  * The ONE ingress for a database row. `agx_get_list_full()` and `agx_search()`
- * return the same 19 columns (search adds two ranking columns), so both come
+ * return the same list columns (search adds two ranking columns), so both come
  * through here and produce the identical `AgentSummary`.
  *
+ * UNKNOWN COLUMNS ARE IGNORED, BY DESIGN. Every column is read by NAME, so an
+ * additive platform migration (the way `orchestra` arrived) reaches consumers
+ * on `latest` without a package release, and an older database simply yields
+ * `null` for a column it does not have yet.
+ *
  * Typed over `unknown` on purpose: the truth of this boundary is a
  * HOST-generated Supabase type this package cannot see (the `@ai-matrx/data`
  * 0.2.1 lesson). Narrowing happens here, once, loudly — a row that is not an
@@ -665,6 +154,13 @@ declare function createMemoryStorage(): AgentCatalogStorage;
 declare function defaultStorage(): AgentCatalogStorage;
 declare function readCachedDefaultRow(storage: AgentCatalogStorage, mandateKey: string): ResolvedDefaultRow | null;
 declare function writeCachedDefaultRow(storage: AgentCatalogStorage, resolved: ResolvedDefaultRow): void;
+/**
+ * Read the cached row from EITHER storage shape. A store that throws or answers
+ * with a rejected promise costs a first paint, never correctness.
+ */
+declare function readCachedDefaultRowAsync(storage: AgentCatalogStorageLike, mandateKey: string): Promise<ResolvedDefaultRow | null>;
+/** Write the cached row to EITHER storage shape. */
+declare function writeCachedDefaultRowAsync(storage: AgentCatalogStorageLike, resolved: ResolvedDefaultRow): Promise<void>;
 /** Build the `mandate:<key>` row from a resolved Holder. Never hardcodes text. */
 declare function defaultRowFromResolution(resolved: ResolvedDefaultRow): AgentSummary;
 /**
@@ -676,7 +172,7 @@ interface ResolveDefaultRowArgs {
     mandateKey: string;
     transport: AgentCatalogTransport;
     client: AgentCatalogClient;
-    storage: AgentCatalogStorage;
+    storage: AgentCatalogStorageLike;
     errorSink: AgentCatalogErrorSink;
     /** Look the Holder up in the rows this catalog already holds. */
     lookupRow: (agentId: string) => AgentSummary | undefined;
@@ -865,4 +361,4 @@ declare const selectTotalFavoriteAgentsCount: (a: readonly AgentSummary[]) => nu
 /** @internal Test-only: forget every session-shared value. */
 declare function _resetCatalogGlobalState(): void;
 
-export { AGENT_CARDS_LIMIT_DESKTOP, AGENT_CARDS_LIMIT_MOBILE, AGENT_LIST_ITEMS_PER_PAGE, AGENT_NONE_SENTINEL, AGENT_SEARCH_LIMIT, type AgentAccessFilter, type AgentAccessLevel, type AgentArchFilter, type AgentCatalog, type AgentCatalogAgentType, type AgentCatalogClient, type AgentCatalogConfig, AgentCatalogConfigError, type AgentCatalogErrorSink, type AgentCatalogIdentity, type AgentCatalogLabels, type AgentCatalogNavigate, type AgentCatalogNotifier, type AgentCatalogOpenPeek, AgentCatalogReadError, type AgentCatalogResolveHref, type AgentCatalogRpcCall, type AgentCatalogSchemaReport, type AgentCatalogState, type AgentCatalogStatus, type AgentCatalogStorage, type AgentCatalogTableQuery, type AgentCatalogTransport, type AgentConsumerPatch, type AgentConsumerState, type AgentFavFilter, type AgentId, type AgentListPage, type AgentSearchable, type AgentServerSearchResult, type AgentSortOption, type AgentSummary, type AgentTab, type AssertAgentCatalogSchemaOptions, DEFAULT_AGENT_CATALOG_LABELS, DEFAULT_AGENT_CONSUMER_STATE, type DefaultRowState, MandateDefaultRowError, type MandateResolutionVerdict, type PgErrorLike, type PgResultLike, type ResolveDefaultRowArgs, type ResolveDefaultRowOutcome, type ResolvedDefaultRow, _resetCatalogGlobalState, agentConsumerHasActiveFilters, agentListEmptyLabel, agentMatchesSearch, applyAgentSortComparator, asAgentId, assertAgentCatalogSchema, computeAgentSearchScore, createAgentCatalog, createMemoryStorage, defaultRowFromResolution, defaultStorage, detectDefaultRowDrift, filterBuiltinTypeAgents, filterUserTypeAgents, getRegisteredAgentCatalog, isMandateAgentId, makeSelectFilteredAgents, makeSelectFilteredAgentsCount, makeSelectFilteredBuiltinAgents, makeSelectFilteredBuiltinAgentsCount, makeSelectFilteredOwnedAgents, makeSelectFilteredSharedAgents, makeSelectOwnedAgentCards, makeSelectOwnedAgentListItems, makeSelectSharedAgentCards, makeSelectSharedAgentListItems, mandateAgentId, memoize1, memoize2, memoize3, parseMandateResolution, readAgentCatalogRows, readCachedDefaultRow, readSingleAgentRow, resolveDefaultRow, searchAgentsOnServer, selectAllAgentCategories, selectAllAgentTags, selectAllSystemAgentCategories, selectAllSystemAgentTags, selectBuiltinTypeAgents, selectTotalBuiltinAgentsCount, selectTotalFavoriteAgentsCount, selectTotalOwnedAgentsCount, selectTotalSharedAgentsCount, selectTotalUserAgentsCount, selectUserTypeAgents, shouldDefaultAgentListToPublicTab, sortFilteredAgents, toAgentSummary, writeAgentFavorite, writeCachedDefaultRow };
+export { AGENT_CARDS_LIMIT_DESKTOP, AGENT_CARDS_LIMIT_MOBILE, AGENT_LIST_ITEMS_PER_PAGE, AGENT_SEARCH_LIMIT, AgentCatalogClient, AgentCatalogErrorSink, AgentCatalogLabels, AgentCatalogReadError, AgentCatalogStorage, AgentCatalogStorageLike, AgentCatalogTransport, AgentConsumerState, type AgentListPage, type AgentSearchable, type AgentServerSearchResult, AgentSortOption, AgentSummary, AgentTab, MandateDefaultRowError, MandateResolutionVerdict, type ResolveDefaultRowArgs, type ResolveDefaultRowOutcome, ResolvedDefaultRow, _resetCatalogGlobalState, agentConsumerHasActiveFilters, agentListEmptyLabel, agentMatchesSearch, applyAgentSortComparator, computeAgentSearchScore, createMemoryStorage, defaultRowFromResolution, defaultStorage, detectDefaultRowDrift, filterBuiltinTypeAgents, filterUserTypeAgents, makeSelectFilteredAgents, makeSelectFilteredAgentsCount, makeSelectFilteredBuiltinAgents, makeSelectFilteredBuiltinAgentsCount, makeSelectFilteredOwnedAgents, makeSelectFilteredSharedAgents, makeSelectOwnedAgentCards, makeSelectOwnedAgentListItems, makeSelectSharedAgentCards, makeSelectSharedAgentListItems, memoize1, memoize2, memoize3, parseMandateResolution, readAgentCatalogRows, readCachedDefaultRow, readCachedDefaultRowAsync, readSingleAgentRow, resolveDefaultRow, searchAgentsOnServer, selectAllAgentCategories, selectAllAgentTags, selectAllSystemAgentCategories, selectAllSystemAgentTags, selectBuiltinTypeAgents, selectTotalBuiltinAgentsCount, selectTotalFavoriteAgentsCount, selectTotalOwnedAgentsCount, selectTotalSharedAgentsCount, selectTotalUserAgentsCount, selectUserTypeAgents, shouldDefaultAgentListToPublicTab, sortFilteredAgents, toAgentSummary, writeAgentFavorite, writeCachedDefaultRow, writeCachedDefaultRowAsync };