@ai-matrx/agents 0.9.0 → 0.9.2

package/dist/{orchestra-BWJM2MWP.d.cts → orchestra-DljbEiks.d.cts}

@@ -134,8 +134,50 @@ declare const SORT_OPTIONS: {
 type AgentTab = "mine" | "shared" | "all" | "system";
 /** Favorite filter. */
 type AgentFavFilter = "all" | "yes" | "no";
-/** Archive filter. */
+/**
+ * The archive filter — THE ARCHIVED-ITEMS LAW's ONE control, in this
+ * package's existing vocabulary.
+ *
+ * > "everything should have an archive filter, and the default should always
+ * > hide archived, but seeing archived items should be one or two clicks
+ * > away." — Arman, 2026-09-09 (`common-docs/policies/archived-items.md`)
+ *
+ * Three states and no more, identical for every entity on the platform:
+ *
+ * | value      | the platform's words | what the list shows      |
+ * |------------|----------------------|--------------------------|
+ * | `active`   | hide archived        | only un-archived rows    |
+ * | `both`     | show all             | every row                |
+ * | `archived` | archived only        | only archived rows       |
+ *
+ * `active` is the platform default, and it is a KNOB — see
+ * `AgentCatalogConfig.defaults.archiveFilter`.
+ */
 type AgentArchFilter = "active" | "archived" | "both";
+/** Every legal archive-filter value, in the order the control cycles them. */
+declare const ARCHIVE_FILTER_ORDER: readonly AgentArchFilter[];
+interface AgentArchFilterOption {
+    value: AgentArchFilter;
+    /** The platform's own words for the state — what a menu row would read. */
+    label: string;
+    /** What the filter-bar chip reads while this state is the active one. */
+    chip: string;
+}
+/**
+ * 🚨 ONE CONTROL, THREE STATES, SAME WORDS EVERYWHERE. A surface that invents
+ * its own archive vocabulary breaks clause 3 of the law ("the same primitive
+ * everywhere … not a per-feature invention").
+ */
+declare const ARCHIVE_FILTER_OPTIONS: readonly AgentArchFilterOption[];
+/**
+ * The next state of the cycling control: hide archived → show all → archived
+ * only → hide archived. Pure, so the web chip and the native chip cannot
+ * drift apart, and so "the control reveals archived rows in ONE action" is a
+ * testable claim rather than a UI opinion.
+ */
+declare function nextArchFilter(current: AgentArchFilter): AgentArchFilter;
+/** True when `value` is one of the three legal states. */
+declare function isAgentArchFilter(value: unknown): value is AgentArchFilter;
 /**
  * Access level filter.
  * 'any'    = no restriction (default).
@@ -388,6 +430,29 @@ interface AgentCatalogConfig {
     transport?: AgentCatalogTransport;
     /** OPTIONAL — label overrides. */
     labels?: Partial<AgentCatalogLabels>;
+    /**
+     * OPTIONAL — the host's starting values for per-consumer view state.
+     * See `AgentCatalogDefaults`.
+     */
+    defaults?: AgentCatalogDefaults;
+}
+/**
+ * 🚨 OPINIONS BECOME KNOBS (root law 6). The archive filter's initial state is
+ * a configurable default, not code taste — clause 6 of THE ARCHIVED-ITEMS LAW
+ * (`common-docs/policies/archived-items.md`) says so explicitly.
+ *
+ * The PLATFORM default is `"active"` (hide archived) and a host that passes
+ * nothing gets exactly that. A host wires this to whatever its org/user
+ * setting resolves to; an individual picker can still override it per
+ * consumer (`useAgentListCore({ initialArchFilter })`), and the person can
+ * always change it from the control on the filter bar.
+ *
+ * An illegal value is NOT coerced to the default — it throws
+ * `AgentCatalogConfigError`, because a silently-ignored setting is a knob that
+ * lies about being a knob.
+ */
+interface AgentCatalogDefaults {
+    archiveFilter?: AgentArchFilter;
 }
 /**
  * The transport seam, structurally identical to `MatrxTransport` from
@@ -565,6 +630,14 @@ interface AgentCatalog {
     readonly notifier: AgentCatalogNotifier | undefined;
     /** True when this catalog was given a transport and can resolve mandates. */
     readonly canResolveMandates: boolean;
+    /**
+     * The consumer state a brand-new consumer starts from, AFTER the host's
+     * `defaults` knob is applied. Read it instead of
+     * `DEFAULT_AGENT_CONSUMER_STATE` whenever the question is "is this filter at
+     * its default?" — a host that legitimately defaults the archive filter to
+     * "show all" must not have every control render as though it were modified.
+     */
+    readonly consumerDefaults: AgentConsumerState;
     getState(): AgentCatalogState;
     subscribe(listener: () => void): () => void;
     getAgent(agentId: string): AgentSummary | undefined;
@@ -640,4 +713,4 @@ declare function orchestraDepthLine(badge: OrchestraBadge): string | null;
  */
 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 };
+export { nextArchFilter as $, type AgentSummary as A, type AgentCatalogResolveHref as B, type AgentCatalogRpcCall as C, type AgentCatalogSchemaReport as D, type AgentCatalogState as E, type AgentCatalogStatus as F, type AgentCatalogTableQuery as G, type AgentConsumerPatch as H, type AgentFavFilter as I, type AgentId as J, type AssertAgentCatalogSchemaOptions as K, DEFAULT_AGENT_CATALOG_LABELS as L, type MandateResolutionVerdict as M, DEFAULT_AGENT_CONSUMER_STATE as N, type DefaultRowState as O, type OrchestraBadge as P, type PgErrorLike as Q, type ResolvedDefaultRow as R, type PgResultLike as S, SORT_OPTIONS as T, asAgentId as U, assertAgentCatalogSchema as V, createAgentCatalog as W, getRegisteredAgentCatalog as X, isAgentArchFilter as Y, isMandateAgentId as Z, mandateAgentId as _, type AgentCatalogClient as a, orchestraDelegatesLine as a0, orchestraDepthLine as a1, orchestraLabel as a2, orchestraModeLabel as a3, type AgentCatalogTransport as b, type AgentCatalogStorageLike as c, type AgentCatalogErrorSink as d, type AgentCatalogStorage as e, type AgentArchFilter as f, type AgentTab as g, type AgentCatalogLabels as h, type AgentConsumerState as i, type AgentSortOption as j, AGENT_NONE_SENTINEL as k, ARCHIVE_FILTER_OPTIONS as l, ARCHIVE_FILTER_ORDER as m, type AgentAccessFilter as n, type AgentAccessLevel as o, type AgentArchFilterOption as p, type AgentCatalog as q, type AgentCatalogAgentType as r, type AgentCatalogAsyncStorage as s, type AgentCatalogConfig as t, AgentCatalogConfigError as u, type AgentCatalogDefaults as v, type AgentCatalogIdentity as w, type AgentCatalogNavigate as x, type AgentCatalogNotifier as y, type AgentCatalogOpenPeek as z };

package/dist/{orchestra-BWJM2MWP.d.ts → orchestra-DljbEiks.d.ts}

@@ -134,8 +134,50 @@ declare const SORT_OPTIONS: {
 type AgentTab = "mine" | "shared" | "all" | "system";
 /** Favorite filter. */
 type AgentFavFilter = "all" | "yes" | "no";
-/** Archive filter. */
+/**
+ * The archive filter — THE ARCHIVED-ITEMS LAW's ONE control, in this
+ * package's existing vocabulary.
+ *
+ * > "everything should have an archive filter, and the default should always
+ * > hide archived, but seeing archived items should be one or two clicks
+ * > away." — Arman, 2026-09-09 (`common-docs/policies/archived-items.md`)
+ *
+ * Three states and no more, identical for every entity on the platform:
+ *
+ * | value      | the platform's words | what the list shows      |
+ * |------------|----------------------|--------------------------|
+ * | `active`   | hide archived        | only un-archived rows    |
+ * | `both`     | show all             | every row                |
+ * | `archived` | archived only        | only archived rows       |
+ *
+ * `active` is the platform default, and it is a KNOB — see
+ * `AgentCatalogConfig.defaults.archiveFilter`.
+ */
 type AgentArchFilter = "active" | "archived" | "both";
+/** Every legal archive-filter value, in the order the control cycles them. */
+declare const ARCHIVE_FILTER_ORDER: readonly AgentArchFilter[];
+interface AgentArchFilterOption {
+    value: AgentArchFilter;
+    /** The platform's own words for the state — what a menu row would read. */
+    label: string;
+    /** What the filter-bar chip reads while this state is the active one. */
+    chip: string;
+}
+/**
+ * 🚨 ONE CONTROL, THREE STATES, SAME WORDS EVERYWHERE. A surface that invents
+ * its own archive vocabulary breaks clause 3 of the law ("the same primitive
+ * everywhere … not a per-feature invention").
+ */
+declare const ARCHIVE_FILTER_OPTIONS: readonly AgentArchFilterOption[];
+/**
+ * The next state of the cycling control: hide archived → show all → archived
+ * only → hide archived. Pure, so the web chip and the native chip cannot
+ * drift apart, and so "the control reveals archived rows in ONE action" is a
+ * testable claim rather than a UI opinion.
+ */
+declare function nextArchFilter(current: AgentArchFilter): AgentArchFilter;
+/** True when `value` is one of the three legal states. */
+declare function isAgentArchFilter(value: unknown): value is AgentArchFilter;
 /**
  * Access level filter.
  * 'any'    = no restriction (default).
@@ -388,6 +430,29 @@ interface AgentCatalogConfig {
     transport?: AgentCatalogTransport;
     /** OPTIONAL — label overrides. */
     labels?: Partial<AgentCatalogLabels>;
+    /**
+     * OPTIONAL — the host's starting values for per-consumer view state.
+     * See `AgentCatalogDefaults`.
+     */
+    defaults?: AgentCatalogDefaults;
+}
+/**
+ * 🚨 OPINIONS BECOME KNOBS (root law 6). The archive filter's initial state is
+ * a configurable default, not code taste — clause 6 of THE ARCHIVED-ITEMS LAW
+ * (`common-docs/policies/archived-items.md`) says so explicitly.
+ *
+ * The PLATFORM default is `"active"` (hide archived) and a host that passes
+ * nothing gets exactly that. A host wires this to whatever its org/user
+ * setting resolves to; an individual picker can still override it per
+ * consumer (`useAgentListCore({ initialArchFilter })`), and the person can
+ * always change it from the control on the filter bar.
+ *
+ * An illegal value is NOT coerced to the default — it throws
+ * `AgentCatalogConfigError`, because a silently-ignored setting is a knob that
+ * lies about being a knob.
+ */
+interface AgentCatalogDefaults {
+    archiveFilter?: AgentArchFilter;
 }
 /**
  * The transport seam, structurally identical to `MatrxTransport` from
@@ -565,6 +630,14 @@ interface AgentCatalog {
     readonly notifier: AgentCatalogNotifier | undefined;
     /** True when this catalog was given a transport and can resolve mandates. */
     readonly canResolveMandates: boolean;
+    /**
+     * The consumer state a brand-new consumer starts from, AFTER the host's
+     * `defaults` knob is applied. Read it instead of
+     * `DEFAULT_AGENT_CONSUMER_STATE` whenever the question is "is this filter at
+     * its default?" — a host that legitimately defaults the archive filter to
+     * "show all" must not have every control render as though it were modified.
+     */
+    readonly consumerDefaults: AgentConsumerState;
     getState(): AgentCatalogState;
     subscribe(listener: () => void): () => void;
     getAgent(agentId: string): AgentSummary | undefined;
@@ -640,4 +713,4 @@ declare function orchestraDepthLine(badge: OrchestraBadge): string | null;
  */
 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 };
+export { nextArchFilter as $, type AgentSummary as A, type AgentCatalogResolveHref as B, type AgentCatalogRpcCall as C, type AgentCatalogSchemaReport as D, type AgentCatalogState as E, type AgentCatalogStatus as F, type AgentCatalogTableQuery as G, type AgentConsumerPatch as H, type AgentFavFilter as I, type AgentId as J, type AssertAgentCatalogSchemaOptions as K, DEFAULT_AGENT_CATALOG_LABELS as L, type MandateResolutionVerdict as M, DEFAULT_AGENT_CONSUMER_STATE as N, type DefaultRowState as O, type OrchestraBadge as P, type PgErrorLike as Q, type ResolvedDefaultRow as R, type PgResultLike as S, SORT_OPTIONS as T, asAgentId as U, assertAgentCatalogSchema as V, createAgentCatalog as W, getRegisteredAgentCatalog as X, isAgentArchFilter as Y, isMandateAgentId as Z, mandateAgentId as _, type AgentCatalogClient as a, orchestraDelegatesLine as a0, orchestraDepthLine as a1, orchestraLabel as a2, orchestraModeLabel as a3, type AgentCatalogTransport as b, type AgentCatalogStorageLike as c, type AgentCatalogErrorSink as d, type AgentCatalogStorage as e, type AgentArchFilter as f, type AgentTab as g, type AgentCatalogLabels as h, type AgentConsumerState as i, type AgentSortOption as j, AGENT_NONE_SENTINEL as k, ARCHIVE_FILTER_OPTIONS as l, ARCHIVE_FILTER_ORDER as m, type AgentAccessFilter as n, type AgentAccessLevel as o, type AgentArchFilterOption as p, type AgentCatalog as q, type AgentCatalogAgentType as r, type AgentCatalogAsyncStorage as s, type AgentCatalogConfig as t, AgentCatalogConfigError as u, type AgentCatalogDefaults as v, type AgentCatalogIdentity as w, type AgentCatalogNavigate as x, type AgentCatalogNotifier as y, type AgentCatalogOpenPeek as z };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai-matrx/agents",
-  "version": "0.9.0",
+  "version": "0.9.2",
   "description": "Portable AI Matrx agent stream protocol, event projection, and safe result-presentation primitives.",
   "type": "module",
   "main": "./dist/index.cjs",