@ai-matrx/agents 0.7.1 → 0.9.0

package/dist/orchestra-BWJM2MWP.d.cts

@@ -0,0 +1,643 @@
+/**
+ * `@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;
+}
+/**
+ * The SAME seam for a platform whose only key-value store is asynchronous.
+ *
+ * 🚨 WHY THIS EXISTS (0.9.0). React Native has no `localStorage`; every Expo
+ * app's store (`@react-native-async-storage/async-storage`, `expo-secure-store`,
+ * MMKV's async face) answers with a promise. Before this, a native host had
+ * exactly two options — hand the package a storage that lies by returning
+ * `null` synchronously, or lose the default row's first paint entirely. Both
+ * are the silent degradation this package exists to refuse.
+ *
+ * The shape is `AsyncStorage`'s own, so an Expo host passes AsyncStorage
+ * directly with no adapter. Every method may answer synchronously OR with a
+ * promise, which is what makes `AgentCatalogStorage` a subtype of this one:
+ * the WEB PATH IS UNCHANGED — a sync storage still resolves in the same
+ * microtask, and `readCachedDefaultRow`/`writeCachedDefaultRow` keep their
+ * synchronous signatures for every existing caller.
+ */
+interface AgentCatalogAsyncStorage {
+    getItem(key: string): string | null | Promise<string | null>;
+    setItem(key: string, value: string): void | Promise<void>;
+    removeItem(key: string): void | Promise<void>;
+}
+/** Either storage shape. What `AgentCatalogConfig.storage` accepts. */
+type AgentCatalogStorageLike = AgentCatalogStorage | AgentCatalogAsyncStorage;
+/** 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` and `AgentCatalogAsyncStorage`. A
+     * synchronous store (the web `localStorage` default) and an asynchronous
+     * one (React Native's `AsyncStorage`) are both accepted verbatim.
+     */
+    storage?: AgentCatalogStorageLike;
+    /**
+     * 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;
+
+/**
+ * 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;
+
+export { type AgentSummary as A, type AgentCatalogStatus as B, type AgentCatalogTableQuery as C, type AgentConsumerPatch as D, type AgentFavFilter as E, type AgentId as F, type AssertAgentCatalogSchemaOptions as G, DEFAULT_AGENT_CATALOG_LABELS as H, DEFAULT_AGENT_CONSUMER_STATE as I, type DefaultRowState as J, type PgResultLike as K, asAgentId as L, type MandateResolutionVerdict as M, assertAgentCatalogSchema as N, type OrchestraBadge as O, type PgErrorLike as P, createAgentCatalog as Q, type ResolvedDefaultRow as R, SORT_OPTIONS as S, getRegisteredAgentCatalog as T, isMandateAgentId as U, mandateAgentId as V, orchestraDelegatesLine as W, orchestraDepthLine as X, orchestraLabel as Y, orchestraModeLabel as Z, type AgentCatalogClient as a, type AgentCatalogTransport as b, type AgentCatalogStorageLike as c, type AgentCatalogErrorSink as d, type AgentCatalogStorage as e, type AgentTab as f, type AgentCatalogLabels as g, type AgentConsumerState as h, type AgentSortOption as i, AGENT_NONE_SENTINEL as j, type AgentAccessFilter as k, type AgentAccessLevel as l, type AgentArchFilter as m, type AgentCatalog as n, type AgentCatalogAgentType as o, type AgentCatalogAsyncStorage as p, type AgentCatalogConfig as q, AgentCatalogConfigError as r, type AgentCatalogIdentity as s, type AgentCatalogNavigate as t, type AgentCatalogNotifier as u, type AgentCatalogOpenPeek as v, type AgentCatalogResolveHref as w, type AgentCatalogRpcCall as x, type AgentCatalogSchemaReport as y, type AgentCatalogState as z };