@ai-matrx/agents 0.8.0 → 0.9.1

package/dist/catalog/index.d.cts

@@ -1,587 +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 & {});
-/**
- * Present on a catalog row ONLY when that agent is an **Orchestra** — a
- * conductor that delegates to member agents at run time. Choosing one for a
- * step, a chat or a workflow node runs the whole ensemble, so a person has to
- * be able to SEE that before choosing, not discover it from the run.
- *
- * The DB decides. `agx_get_list_full` / `agx_get_list` / `agx_search` build
- * this from `platform.associations` (the conductor self-edge plus its member
- * edges) in one `agx_orchestra_badges()` join — never a second fetch, and
- * never a per-row read. `null` for every ordinary agent.
- *
- * History: the badge lived only in the Python `GET /agents` route, so every
- * client lost it when the pickers moved to the RPC. It is a ROW FIELD now, in
- * the one read every client shares.
- */
-interface OrchestraBadge {
-    /** How the ensemble runs: `supervisor` | `sequential` | `parallel` | `dag`, or a future mode verbatim. */
-    mode: string;
-    /** The composition's one-line description, when its author wrote one. */
-    tagline: string | null;
-    /**
-     * The per-composition delegation-depth budget AS DECLARED, or `null` when
-     * the composition declares none. Deliberately NOT defaulted here: the
-     * platform's fallback ceiling is enforced by the server that runs the
-     * ensemble, and a badge that invented a number would be reporting a promise
-     * nobody made.
-     */
-    depthBudget: number | null;
-    /** Member edges. From the ROW count, so an unlabelled ensemble still counts. */
-    memberCount: number;
-    /** Only REAL role titles — an ensemble with unlabelled edges yields `[]`. */
-    memberTitles: 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;
-    /**
-     * The Orchestra badge, or `null` for an ordinary agent. Strict: every row
-     * carries the key, so a surface reads `agent.orchestra` and never has to ask
-     * whether the column existed.
-     */
-    orchestra: OrchestraBadge | 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";
-/**
- * The sort choices a picker offers, in order. PURE DATA, so it lives in the
- * pure entry: a server-reachable manifest reads it at module scope, and
- * importing it from the client-stamped `./catalog/react` bundle dragged React
- * into a server graph for the sake of five string pairs. `./catalog/react`
- * re-exports it unchanged, so no consumer has to move.
- *
- * (Written "client-stamped", never with the literal directive: this comment is
- * emitted into `dist/catalog/index.d.ts`, and the tarball canary rightly
- * refuses that directive anywhere in a PURE entry.)
- */
-declare const SORT_OPTIONS: {
-    value: AgentSortOption;
-    label: string;
-}[];
-/** 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;
-    /**
-     * Whether `agx_get_list_full` carries the `orchestra` badge column (added to
-     * the platform 2026-09-08).
-     *
-     * NOT a violation when absent — the picker degrades to no conductor marker,
-     * which is honest — but it is never SILENT either: a `false` here is the one
-     * signal that tells a host "this database predates the badge" instead of
-     * leaving someone to wonder why their Orchestra looks like a plain agent.
-     * `null` means the probe could not tell (the caller can see no agents at
-     * all), never "fine".
-     */
-    orchestraColumn: 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 AgentArchFilter, j as AgentSortOption } from '../orchestra-CID-rsu8.cjs';
+export { k as AGENT_NONE_SENTINEL, l as AgentAccessFilter, m as AgentAccessLevel, 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-CID-rsu8.cjs';
 
 /**
  * catalog/data.ts — @ai-matrx/agents/catalog
@@ -680,35 +98,6 @@ declare function writeAgentFavorite(client: AgentCatalogClient, agentId: string,
  */
 declare function toAgentSummary(raw: unknown): AgentSummary | null;
 
-/**
- * catalog/orchestra.ts — @ai-matrx/agents/catalog
- *
- * Creator words for an Orchestra badge. A VERBATIM port of the helpers the
- * Workflow Studio's hand-rolled picker carried (`apps/workflow-studio/src/
- * hooks/use-agents.ts` before `c0f958b43`), lifted here so every client says
- * the same sentence about the same ensemble.
- *
- * Pure — no React, no DOM. The row shape is `OrchestraBadge` in `./types`.
- */
-
-declare function orchestraModeLabel(mode: string): string;
-/** Human label for a badge: "Orchestra · supervisor · 3 members" (singular-safe). */
-declare function orchestraLabel(badge: OrchestraBadge): string;
-/**
- * The member-call ceiling in Creator language ("Team members can call helpers
- * up to 2 levels deep"), or `null` when the composition declared none. A badge
- * never invents the platform default: the server that runs the ensemble owns
- * that number, and printing a promise nobody made is worse than printing
- * nothing.
- */
-declare function orchestraDepthLine(badge: OrchestraBadge): string | null;
-/**
- * One visible line naming who the Orchestra delegates to, collapsing past
- * `limit` into "+N more". `null` when no member carries a real role title —
- * "Member, Member, Member" is noise that reads like data.
- */
-declare function orchestraDelegatesLine(badge: OrchestraBadge, limit?: number): string | null;
-
 /**
  * catalog/default-row.ts — @ai-matrx/agents/catalog
  *
@@ -765,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;
 /**
@@ -776,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;
@@ -861,7 +257,18 @@ declare function agentMatchesSearch(agent: AgentSearchable, query: string): bool
  * 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.
+ * ported.
+ *
+ * 🚨 TWO DELIBERATE DEPARTURES FROM THE ORIGINAL, both defects the port
+ * inherited and 0.9.1 fixes at the class (see CHANGELOG 0.9.1):
+ *
+ *   F1 — every sort now ends on `id` ASC, the same final key `agx_get_list`
+ *        ends on, so the order of TIED rows is defined by the rows instead of
+ *        by whichever transport the host used to fetch them.
+ *   F5 — the tab-badge counts honour the archive filter, so the badge, the
+ *        footer and the rendered rows are the same number.
+ *
+ * Everything else below is byte-identical to the original.
  */
 
 declare const AGENT_CARDS_LIMIT_DESKTOP = 8;
@@ -877,6 +284,31 @@ declare const AGENT_LIST_ITEMS_PER_PAGE = 20;
 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;
+/**
+ * 🚨 THE FINAL TIEBREAKER. `agx_get_list` orders
+ * `is_favorite DESC, updated_at DESC, id` — `id` ASCENDING is the unique key
+ * that makes the SERVER's order TOTAL. Every sort in this file ends on the
+ * same key, so the rendered order is a function of the ROWS and never of the
+ * order they happened to arrive in.
+ *
+ * Why a raw `<` / `>` and not `localeCompare`: Postgres orders `uuid` by its
+ * 16 raw bytes. The canonical text form is lowercase hex with dashes at fixed
+ * positions, so a codepoint comparison of those strings reproduces the
+ * database's order exactly. A locale collator does not — it is free to fold
+ * case or ignore punctuation, and would silently diverge from the server on
+ * precisely the ties this key exists to settle.
+ */
+declare function compareAgentIds(a: AgentSummary, b: AgentSummary): number;
+/**
+ * The chosen sort key, then `id`. TOTAL for every option.
+ *
+ * Before 0.9.1 each branch below returned 0 for tied rows, which left their
+ * relative order to whatever `Array.prototype.sort` had been handed — i.e. to
+ * the transport. A host that fetched the RPC in one shot kept the server's
+ * favourites-first/`updated_at DESC` order for ties; a host that paged it with
+ * `order=id.asc` kept id-ASC. Same rows, same filters, two different screens.
+ * The key below is the server's own, so both now render the server's answer.
+ */
 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[];
@@ -894,6 +326,15 @@ declare const selectAllSystemAgentTags: (a: readonly AgentSummary[]) => string[]
 declare const selectUserTypeAgents: (a: readonly AgentSummary[]) => AgentSummary[];
 /** Builtin/system agents only. For chat pickers and full catalogues. */
 declare const selectBuiltinTypeAgents: (a: readonly AgentSummary[]) => AgentSummary[];
+/**
+ * The ONE ordering rule, and it is TOTAL on every path.
+ *
+ *   searching:     score DESC → server rank ASC → sort key → id ASC
+ *   not searching: favourites first (when asked) → sort key → id ASC
+ *
+ * `id` ASC is the final key `agx_get_list` itself ends on, so two hosts that
+ * fetched the same rows through different transports render the same screen.
+ */
 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[];
@@ -943,6 +384,35 @@ declare const makeSelectFilteredAgentsCount: () => (a: readonly AgentSummary[],
 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;
+/**
+ * 🚨 A BADGE COUNTS WHAT THE TAB RENDERS. Nothing else.
+ *
+ * Before 0.9.1 these five counted every user-type row, archived included,
+ * while `filterUserTypeAgents` (archive filter `active`, the default) hid the
+ * archived ones. The badge said "Mine 416", the list showed 412 rows and the
+ * footer said "412 agents" — one screen, three numbers, one of them a lie
+ * about agents the user cannot see or reach from there.
+ *
+ * `is_archived` is now honoured by the same rule the list uses, so the badge,
+ * the footer and the rows agree on every tab and under every archive filter.
+ * The system tab is the exception with a reason: `filterBuiltinTypeAgents`
+ * applies no archive filter (a builtin belongs to the platform and is never
+ * the user's to archive), so its count applies none either — it already
+ * counted exactly what it rendered.
+ */
+declare function agentMatchesArchiveFilter(agent: AgentSummary, archFilter: AgentArchFilter): boolean;
+/**
+ * The four tab badges for a consumer's CURRENT archive filter — the numbers
+ * `useAgentListCore` puts on the tab strip. Flip the archive filter to
+ * "archived" and the badges follow the list into the archive.
+ */
+declare const selectAgentTabCounts: (a: readonly AgentSummary[], b: AgentArchFilter) => {
+    mine: number;
+    shared: number;
+    all: number;
+    system: number;
+};
+/** Live user-type agents the default (`active`) list renders. */
 declare const selectTotalUserAgentsCount: (a: readonly AgentSummary[]) => number;
 declare const selectTotalOwnedAgentsCount: (a: readonly AgentSummary[]) => number;
 declare const selectTotalSharedAgentsCount: (a: readonly AgentSummary[]) => number;
@@ -965,4 +435,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 OrchestraBadge, type PgErrorLike, type PgResultLike, type ResolveDefaultRowArgs, type ResolveDefaultRowOutcome, type ResolvedDefaultRow, SORT_OPTIONS, _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, orchestraDelegatesLine, orchestraDepthLine, orchestraLabel, orchestraModeLabel, 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, AgentArchFilter, 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, agentMatchesArchiveFilter, agentMatchesSearch, applyAgentSortComparator, compareAgentIds, 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, selectAgentTabCounts, selectAllAgentCategories, selectAllAgentTags, selectAllSystemAgentCategories, selectAllSystemAgentTags, selectBuiltinTypeAgents, selectTotalBuiltinAgentsCount, selectTotalFavoriteAgentsCount, selectTotalOwnedAgentsCount, selectTotalSharedAgentsCount, selectTotalUserAgentsCount, selectUserTypeAgents, shouldDefaultAgentListToPublicTab, sortFilteredAgents, toAgentSummary, writeAgentFavorite, writeCachedDefaultRow, writeCachedDefaultRowAsync };