@ai-matrx/agents 0.6.2 → 0.7.1

package/dist/catalog/index.d.ts

@@ -0,0 +1,868 @@
+/**
+ * `@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;
+
+/**
+ * catalog/data.ts — @ai-matrx/agents/catalog
+ *
+ * Every database call the catalog makes, and nothing else. Four of them:
+ *
+ *   1. `agx_get_list_full()` — the complete catalogue (owned + directly-shared
+ *      + org-shared user agents, unioned with active builtins).
+ *   2. `agx_search(p_query, p_deep, p_limit, p_offset)` — tier-2 server search.
+ *   3. `agx_resolve_agent_address(p_ids)` — the single-agent name read, used
+ *      when a mandate's Holder is not in the caller's own catalogue.
+ *   4. ONE write: `agent.definition.is_favorite`.
+ *
+ * 🚨 THE LIST READ IS COMPLETE OR IT THROWS. PostgREST caps every response at
+ * `db-max-rows` (1000 on Matrx Main) and reports success — matrx-frontend's
+ * `fetchAgentsListFull` issued a bare `.rpc()` and would silently have
+ * returned 1000 rows of a larger catalogue (the ~400-builtin truncation
+ * incident is the near-miss). Here the read goes through `readAllRows` with
+ * `{ count: "exact" }` and a stable `.order("id")`, so a truncation is a
+ * loud `IncompleteReadError` instead of a confidently short picker.
+ * The DB's own favourites-first/`updated_at` order is irrelevant: every row
+ * is re-sorted client-side by `sortFilteredAgents`.
+ */
+
+/** Server search page size — the frontend's `AGENT_SEARCH_LIMIT`. */
+declare const AGENT_SEARCH_LIMIT = 50;
+declare class AgentCatalogReadError extends Error {
+    readonly name = "AgentCatalogReadError";
+    readonly source: string;
+    constructor(source: string, detail: string);
+}
+/**
+ * Read the WHOLE agent catalogue. Throws rather than returning a partial
+ * list — see the file header.
+ */
+declare function readAgentCatalogRows(client: AgentCatalogClient): Promise<AgentSummary[]>;
+interface AgentServerSearchResult {
+    /** Matched ids in SERVER RANK ORDER. */
+    ids: string[];
+    /** Full rows for every hit — merged additively into the registry. */
+    rows: AgentSummary[];
+}
+/**
+ * Tier-2 server search. Purely ADDITIVE: it widens what the local filter
+ * admits and never removes a row the local scorer already matched.
+ */
+declare function searchAgentsOnServer(client: AgentCatalogClient, args: {
+    query: string;
+    deep?: boolean;
+    limit?: number;
+}): Promise<AgentServerSearchResult>;
+/**
+ * The single-agent read, used when a mandate's resolved Holder is not in the
+ * caller's own catalogue (a platform agent nobody has shared, most often).
+ *
+ * Two existing doors, in order — never a new RPC:
+ *   1. `agx_search` with the id as the query. The scorer awards an exact id
+ *      match 100000, so the row comes back first, and it is the FULL 19-column
+ *      row (name AND description AND category AND tags).
+ *   2. `agx_resolve_agent_address([id])` — the frontend's own name resolver.
+ *      Name and type only, so the row renders with an honest name and no
+ *      description rather than a fabricated one.
+ *
+ * Returns `null` when neither door can name the agent. The caller SCREAMS;
+ * it never invents a label.
+ */
+declare function readSingleAgentRow(client: AgentCatalogClient, agentId: string): Promise<AgentSummary | null>;
+/**
+ * THE ONE WRITE. Mirrors matrx-frontend's `saveAgentField` for this field
+ * exactly: `agent.definition.is_favorite`, addressed by id.
+ */
+declare function writeAgentFavorite(client: AgentCatalogClient, agentId: string, isFavorite: boolean): Promise<void>;
+
+/**
+ * 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
+ * through here and produce the identical `AgentSummary`.
+ *
+ * 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
+ * object is REFUSED rather than half-read.
+ */
+
+/**
+ * Map one raw list/search row. Returns `null` when the row is not an object
+ * or carries no id — the caller reports that to the errorSink and drops it;
+ * a row with no identity cannot be selected, so rendering it would be a lie.
+ */
+declare function toAgentSummary(raw: unknown): AgentSummary | null;
+
+/**
+ * catalog/default-row.ts — @ai-matrx/agents/catalog
+ *
+ * THE DEFAULT ROW, and the drift screamer (design D3).
+ *
+ * What every client used to do: prepend a placeholder row whose id is
+ * `mandate:<key>` and whose name and description are HARDCODED, and let the
+ * server resolve the real Holder at run time. That is how matrx-local's row
+ * came to be labelled "Matrx Desktop Agent" while `local.cloud_chat` actually
+ * resolves to General Chat — a label lying on screen, with nothing anywhere
+ * that could notice.
+ *
+ * What happens here instead:
+ *
+ *   - A picker instance passes `defaultMandateKey`. The package resolves the
+ *     Holder through the aidream door `GET /mandates/{key}/resolution`
+ *     (verified against `aidream/api/routers/mandate_bindings.py`,
+ *     `get_mandate_resolution`, mounted at prefix `/mandates`) using the
+ *     injected `transport`.
+ *     🚨 THE PLATFORM RULE D-R1: a client NEVER walks the mandate ladder
+ *     itself. It asks. That is why a `defaultMandateKey` with no transport is
+ *     a loud config error and not a DB read.
+ *   - The row renders the Holder's REAL name and description, read from the
+ *     catalogue rows already in hand, or through ONE existing single-agent
+ *     read when the Holder is not in this caller's catalogue.
+ *   - The last resolution is cached in the `storage` port for first paint.
+ *   - Whenever the cached row and the LIVE resolution disagree on holder id
+ *     or holder name, the picker shows a PERSISTENT in-picker banner AND the
+ *     `notifier` port fires. Never a console line, never only a console line.
+ *
+ * The row's id stays `mandate:<key>` byte-for-byte, because matrx-extend
+ * (`src/lib/mandates.ts`) and matrx-local (`desktop/src/lib/mandates.ts`)
+ * already hand that exact ref to their hosts.
+ */
+
+declare class MandateDefaultRowError extends Error {
+    readonly name = "MandateDefaultRowError";
+    readonly mandateKey: string;
+    readonly remedy: string;
+    constructor(args: {
+        mandateKey: string;
+        message: string;
+        remedy: string;
+    });
+}
+/** Narrow the server's `MandateResolutionResponse` to what a picker needs. */
+declare function parseMandateResolution(mandateKey: string, raw: unknown): MandateResolutionVerdict;
+/** An in-memory storage, used when the host binds none and there is no DOM. */
+declare function createMemoryStorage(): AgentCatalogStorage;
+/**
+ * DEFAULT storage: `localStorage` when it exists AND answers (a private
+ * window, a service worker, or SSR all fail differently), else memory.
+ */
+declare function defaultStorage(): AgentCatalogStorage;
+declare function readCachedDefaultRow(storage: AgentCatalogStorage, mandateKey: string): ResolvedDefaultRow | null;
+declare function writeCachedDefaultRow(storage: AgentCatalogStorage, resolved: ResolvedDefaultRow): void;
+/** Build the `mandate:<key>` row from a resolved Holder. Never hardcodes text. */
+declare function defaultRowFromResolution(resolved: ResolvedDefaultRow): AgentSummary;
+/**
+ * The drift verdict. Cached vs live: a changed holder id OR a changed holder
+ * name is drift. Returns the sentence to show, or `null` when they agree.
+ */
+declare function detectDefaultRowDrift(cached: ResolvedDefaultRow | null, live: ResolvedDefaultRow): string | null;
+interface ResolveDefaultRowArgs {
+    mandateKey: string;
+    transport: AgentCatalogTransport;
+    client: AgentCatalogClient;
+    storage: AgentCatalogStorage;
+    errorSink: AgentCatalogErrorSink;
+    /** Look the Holder up in the rows this catalog already holds. */
+    lookupRow: (agentId: string) => AgentSummary | undefined;
+}
+interface ResolveDefaultRowOutcome {
+    resolved: ResolvedDefaultRow;
+    row: AgentSummary;
+    /** Non-null when the cached first-paint row disagreed with the live answer. */
+    drift: string | null;
+}
+/**
+ * Ask the server, name the Holder for real, cache the answer, and report
+ * drift. Throws `MandateDefaultRowError` when the mandate cannot produce a
+ * runnable agent — a picker never renders a default row it cannot name.
+ */
+declare function resolveDefaultRow(args: ResolveDefaultRowArgs): Promise<ResolveDefaultRowOutcome>;
+
+/**
+ * catalog/labels.ts — @ai-matrx/agents/catalog
+ *
+ * VERBATIM port of matrx-frontend `features/agents/constants/agent-list-labels.ts`.
+ * The only seam inverted: the two label constants moved into the `labels` port
+ * (`DEFAULT_AGENT_CATALOG_LABELS.publicTab` / `.publicBadge`) so a host can
+ * override them; the FUNCTIONS below keep their exact behaviour.
+ */
+
+declare function agentListEmptyLabel(tab: AgentTab, labels: AgentCatalogLabels): string;
+/** Whether a list picker should default to the public (`system`) tab instead of Mine. */
+declare function shouldDefaultAgentListToPublicTab(args: {
+    userId: string | null;
+    ownedCount: number;
+    agentsLoaded: boolean;
+}): boolean;
+
+/**
+ * The structural shape a record needs to be searchable. Every field except
+ * `id` is optional so both the full gallery record and the slim chat record
+ * satisfy it without adapters.
+ */
+interface AgentSearchable {
+    id: string;
+    name?: string | null;
+    description?: string | null;
+    category?: string | null;
+    tags?: string[] | null;
+    modelId?: string | null;
+    agentType?: string | null;
+    outputFormat?: string | null;
+    sharedByEmail?: string | null;
+}
+/**
+ * Relevance score for an agent against a query. Higher = more relevant.
+ * Returns 0 when nothing matches (0 is the "no match" contract — see
+ * `agentMatchesSearch`).
+ *
+ * Scores only fields carried by the list-level fetches. Message content and
+ * variable definitions are deliberately excluded: they are not loaded by the
+ * list RPCs, so matching them here would be a false promise. Server-side
+ * search owns deep content matching.
+ */
+declare function computeAgentSearchScore(agent: AgentSearchable, query: string): number;
+/** True when the agent matches the query at all. */
+declare function agentMatchesSearch(agent: AgentSearchable, query: string): boolean;
+
+/**
+ * catalog/selectors.ts — @ai-matrx/agents/catalog
+ *
+ * VERBATIM port of matrx-frontend
+ * `features/agents/redux/agent-consumers/selectors.ts`.
+ *
+ * ALL filter, sort, search-scoring, category/tag extraction and pagination
+ * logic lives here — not in components. Two coupling seams inverted, nothing
+ * else:
+ *
+ *   1. `createSelector` (reselect) → `memoize1`/`memoize2`/`memoize3` below,
+ *      the same last-arguments reference-equality memoization reselect
+ *      defaults to. No Redux, no store types.
+ *   2. `AgentDefinitionRecord` → `AgentSummary`, the list-row shape
+ *      `agx_get_list_full` actually returns.
+ *
+ * One structural consequence of (2), recorded rather than hidden: the
+ * frontend's `selectLiveAgents` filters `isVersion` snapshots out of a store
+ * that also holds them. This catalog only ever holds list rows — a version
+ * snapshot cannot enter it — so that filter is a no-op here and is not
+ * ported. Every ordering, tie-break and count below is byte-identical.
+ */
+
+declare const AGENT_CARDS_LIMIT_DESKTOP = 8;
+declare const AGENT_CARDS_LIMIT_MOBILE = 4;
+declare const AGENT_LIST_ITEMS_PER_PAGE = 20;
+/**
+ * Last-arguments memoization on reference equality — reselect's default
+ * `defaultMemoize` behaviour, in eleven lines and with no dependency. A
+ * selector built here is memoized PER INSTANCE, exactly like a
+ * `createSelector` result, so the factories below keep their contract:
+ * build the selector once per (consumerId, …) and reuse it.
+ */
+declare function memoize1<A, R>(fn: (a: A) => R): (a: A) => R;
+declare function memoize2<A, B, R>(fn: (a: A, b: B) => R): (a: A, b: B) => R;
+declare function memoize3<A, B, C, R>(fn: (a: A, b: B, c: C) => R): (a: A, b: B, c: C) => R;
+declare function applyAgentSortComparator(a: AgentSummary, b: AgentSummary, sortBy: AgentSortOption): number;
+/** All unique categories across live USER agents, sorted alphabetically. */
+declare const selectAllAgentCategories: (a: readonly AgentSummary[]) => string[];
+/**
+ * All unique categories across live SYSTEM (builtin) agents. The system tab
+ * gets the same category filter every other tab has — its options just come
+ * from a different population.
+ */
+declare const selectAllSystemAgentCategories: (a: readonly AgentSummary[]) => string[];
+/** All unique tags across live user agents, sorted alphabetically. */
+declare const selectAllAgentTags: (a: readonly AgentSummary[]) => string[];
+/** All unique tags across live SYSTEM (builtin) agents. */
+declare const selectAllSystemAgentTags: (a: readonly AgentSummary[]) => string[];
+/** Live user-type agents (excludes builtins). */
+declare const selectUserTypeAgents: (a: readonly AgentSummary[]) => AgentSummary[];
+/** Builtin/system agents only. For chat pickers and full catalogues. */
+declare const selectBuiltinTypeAgents: (a: readonly AgentSummary[]) => AgentSummary[];
+declare function sortFilteredAgents(filtered: AgentSummary[], consumer: AgentConsumerState): AgentSummary[];
+/** User-type agents — mine / shared / all tabs with full consumer filters. */
+declare function filterUserTypeAgents(agents: readonly AgentSummary[], consumer: AgentConsumerState): AgentSummary[];
+/**
+ * Builtin/system agents (tab === "system").
+ *
+ * Gets the SAME filter surface every other tab has — search, favorites,
+ * category, tags, sort. Ownership/archive/access filters are meaningless here
+ * (a builtin is always active and belongs to the platform), so those are the
+ * only ones skipped. A picker that offers less on one tab than another is the
+ * exact half-built shape this list exists to prevent.
+ */
+declare function filterBuiltinTypeAgents(agents: readonly AgentSummary[], consumer: AgentConsumerState): AgentSummary[];
+/** Factory: owned user-type agents with consumer filters applied (ignores tab). */
+declare const makeSelectFilteredOwnedAgents: () => (a: readonly AgentSummary[], b: AgentConsumerState) => AgentSummary[];
+/** Factory: shared user-type agents with consumer filters applied (ignores tab). */
+declare const makeSelectFilteredSharedAgents: () => (a: readonly AgentSummary[], b: AgentConsumerState) => AgentSummary[];
+/**
+ * Factory: filters and sorts agents for a consumer. User tabs (mine / shared /
+ * all) draw from user-type agents; the system tab draws from builtins.
+ *
+ * `includeSystemInAll` is the ADMIN reading of the "All" tab. For a normal
+ * user, system agents are a separate catalogue and "All" means "all of MY
+ * agents". For an admin surface, system agents ARE their agents — so "All"
+ * must be a single blended list, with each row still labelled (the `system`
+ * badge on `AgentRow`) so the two are never confused.
+ */
+declare const makeSelectFilteredAgents: (includeSystemInAll?: boolean) => (a: readonly AgentSummary[], b: AgentConsumerState) => AgentSummary[];
+/** Factory: filters and sorts builtin agents for the chat agent picker. */
+declare const makeSelectFilteredBuiltinAgents: () => (a: readonly AgentSummary[], b: AgentConsumerState) => AgentSummary[];
+interface AgentListPage {
+    items: AgentSummary[];
+    hasMore: boolean;
+    totalAfterCards: number;
+}
+/** Factory: slices filtered owned agents into the "cards" hero section. */
+declare const makeSelectOwnedAgentCards: (isMobile: boolean) => (a: readonly AgentSummary[], b: AgentConsumerState) => AgentSummary[];
+/** Factory: paginated list items for owned agents (everything after cards). */
+declare const makeSelectOwnedAgentListItems: (isMobile: boolean) => (a: readonly AgentSummary[], b: AgentConsumerState) => AgentListPage;
+/** Factory: slices filtered shared agents into the "cards" hero section. */
+declare const makeSelectSharedAgentCards: (isMobile: boolean) => (a: readonly AgentSummary[], b: AgentConsumerState) => AgentSummary[];
+/** Factory: paginated list items for shared agents (everything after cards). */
+declare const makeSelectSharedAgentListItems: (isMobile: boolean) => (a: readonly AgentSummary[], b: AgentConsumerState) => AgentListPage;
+/** Factory: total count of filtered agents for a consumer. */
+declare const makeSelectFilteredAgentsCount: () => (a: readonly AgentSummary[], b: AgentConsumerState) => number;
+/** Factory: total count of filtered builtin agents for a consumer. */
+declare const makeSelectFilteredBuiltinAgentsCount: () => (a: readonly AgentSummary[], b: AgentConsumerState) => number;
+/** Returns whether a consumer has any non-default filters active. */
+declare function agentConsumerHasActiveFilters(consumer: AgentConsumerState, defaults: AgentConsumerState): boolean;
+declare const selectTotalUserAgentsCount: (a: readonly AgentSummary[]) => number;
+declare const selectTotalOwnedAgentsCount: (a: readonly AgentSummary[]) => number;
+declare const selectTotalSharedAgentsCount: (a: readonly AgentSummary[]) => number;
+declare const selectTotalBuiltinAgentsCount: (a: readonly AgentSummary[]) => number;
+declare const selectTotalFavoriteAgentsCount: (a: readonly AgentSummary[]) => number;
+
+/**
+ * catalog/global-state.ts — @ai-matrx/agents/catalog
+ *
+ * 🚨 MODULE-LEVEL MUTABLE STATE IS BANNED IN THIS PACKAGE. With dual ESM+CJS
+ * output and `splitting: false`, each loader graph instantiates its own copy
+ * of every module — a module-level variable would silently split the
+ * in-flight dedupe (so the "one RPC for ~20 mounting surfaces" collapse
+ * would become two), the freshness stamp, the catalog registry, and the
+ * default-row cache. Everything session-shared therefore lives on
+ * `globalThis` under a `Symbol.for` slot, exactly like
+ * `@ai-matrx/kit`'s confirm opener. Never "clean this up" into module locals.
+ */
+
+/** @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 };