@ai-matrx/agents 0.38.4 → 0.40.0

package/dist/context/react/index.d.cts

@@ -1,5 +1,19 @@
 import * as react from 'react';
 
+/**
+ * @ai-matrx/agents/context — the context value rules, headless.
+ *
+ * Contract: common-docs/systems/scopes-context/context-delivery/RULES.md.
+ * Parity corpus: ./rules-corpus.json (run here by rules.test.ts and by aidream's
+ * pytest against the Python twin `resolve_context_rule`). Every function here
+ * is pure, zero-React, and safe to import on a server.
+ *
+ * The one flow a client runs per turn:
+ *   rows    = values.map(v => resolveContextRow(v, savedRows, cap))   // what the table shows
+ *   context = buildContextWire(rows)                                   // what the request sends
+ *   …on `context_receipt`: compareReceipt(rows, receipt)               // screen vs server
+ */
+
 /** Which layer decided a field — lowest to highest. */
 type ContextLayer = "default" | "page" | "agent" | "you";
 type ContextDelivery = "inline" | "on_request" | "off";
@@ -173,6 +187,95 @@ interface ContextReceiptMismatch {
     reason?: "self_check";
 }
 
+/**
+ * THE HIERARCHY of the context rules table — where each value sits, and the
+ * switch at every level (Arman, 2026-10-02: "AI Matrx" for the platform's own
+ * values; the page by its section and real name; under it the page's own
+ * declared groups; a switch per level).
+ *
+ * The package never knows a page's groups: the host PLACES each row (level +
+ * group, both already-human labels) and may give a level a host switch (the
+ * page's own on/off). Without a host placement every row is placed by its
+ * origin. A level or group switch is NOT a new kind of rule: it is the
+ * person's per-value include rules for every value in it, written at once
+ * (`includeChanges`), so the server's gate and receipt see exactly the rules
+ * they already honour.
+ */
+
+/** A level of the table: the platform, a page, the chat's attachments. */
+interface ContextLevelRef {
+    /** Stable id (a surface key, `ai_matrx`, `attached`). */
+    id: string;
+    /** Heading, root first: `["Marketing", "Marketing Brand Cockpit"]`, `["AI Matrx"]`. */
+    path: readonly string[];
+    /** Sort order between levels (lower first). */
+    order?: number;
+}
+/** A group inside a level — the page's own declared group, label as declared. */
+interface ContextGroupRef {
+    id: string;
+    label: string;
+    order?: number;
+}
+/** Where one row sits. */
+interface ContextRowPlace {
+    level: ContextLevelRef;
+    /** Null: directly under the level. */
+    group?: ContextGroupRef | null;
+}
+/**
+ * A level whose switch is the host's own (the page on/off for this
+ * conversation) rather than the person's per-value rules. Shown even when the
+ * level has no rows, so the switch never disappears with its values.
+ */
+interface ContextLevelMaster {
+    level: ContextLevelRef;
+    on: boolean;
+    onToggle?: ((next: boolean) => void) | undefined;
+}
+interface ContextHierarchy {
+    place: (row: ResolvedContextRow) => ContextRowPlace;
+    masters?: readonly ContextLevelMaster[];
+}
+interface ContextGroupNode {
+    ref: ContextGroupRef;
+    rows: ResolvedContextRow[];
+}
+interface ContextLevelNode {
+    ref: ContextLevelRef;
+    /** Rows directly under the level (no group). */
+    rows: ResolvedContextRow[];
+    groups: ContextGroupNode[];
+    master: ContextLevelMaster | null;
+}
+/** The platform's own values: the person, their organization, the client. */
+declare const AI_MATRX_LEVEL: ContextLevelRef;
+/** Files and documents attached to the conversation. */
+declare const ATTACHED_LEVEL: ContextLevelRef;
+/** A page the host has not named. */
+declare const PAGE_LEVEL: ContextLevelRef;
+/** The placement a host without one gets: by origin. */
+declare function placeByOrigin(row: ResolvedContextRow): ContextRowPlace;
+/** Rows → levels → groups, in the host's order (stable within equal orders). */
+declare function buildContextLevels(rows: readonly ResolvedContextRow[], hierarchy?: ContextHierarchy | null): ContextLevelNode[];
+/** Every row of a level, groups included. */
+declare function levelRows(level: ContextLevelNode): ResolvedContextRow[];
+/** What the row's include would be with no rule of the person's. */
+declare function inheritedInclude(row: ResolvedContextRow, cap: number): boolean;
+/** One person-rule write: `rule: null` removes the person's rule for that value. */
+interface ContextRuleChange {
+    key: string;
+    surfaceKey: string;
+    rule: SavedContextRule | null;
+}
+/**
+ * A level or group switch: the person's include rule for every value in it
+ * that is not already `include`. A value whose default already gives
+ * `include` loses its own include rule instead (back to the default) — the
+ * saved rules stay minimal and "Reset all" means what it says.
+ */
+declare function includeChanges(rows: readonly ResolvedContextRow[], include: boolean, cap: number): ContextRuleChange[];
+
 type ContextRulesDensity = "compact" | "comfortable";
 interface ContextRulesTableProps {
     rows: readonly ResolvedContextRow[];
@@ -187,13 +290,35 @@ interface ContextRulesTableProps {
     density?: ContextRulesDensity;
     /** Highlights the open row (master/detail). */
     selectedKey?: string | null;
+    /**
+     * Where each row sits (level → group) and the host's level switches. Omit:
+     * rows sit under their origin ("Page", "Attached", "AI Matrx").
+     */
+    hierarchy?: ContextHierarchy | null | undefined;
+    /**
+     * A level or group switch: the person's per-value rules for every value in
+     * it, at once. Omit: level and group switches are hidden (a host master
+     * switch still shows).
+     */
+    onSetInclude?: ((changes: ContextRuleChange[]) => void) | undefined;
     className?: string;
 }
 /**
  * The context rules table: Item | Include | Chars | Inline max. Presentational
  * and state-agnostic — every edit goes out through `onChange`.
  */
-declare function ContextRulesTable({ rows, cap, readOnly, mismatches, onChange, onOpenRow, density, selectedKey, className, }: ContextRulesTableProps): react.JSX.Element;
+declare function ContextRulesTable({ rows, cap, readOnly, mismatches, onChange, onOpenRow, density, selectedKey, hierarchy, onSetInclude, className, }: ContextRulesTableProps): react.JSX.Element;
+
+/**
+ * The header's "N · chars" total. A row whose size is not known yet (an
+ * attachment the server has not measured) never counts as 0: with some sizes
+ * unknown the total is a floor ("1.2k+"), with none known it is "—".
+ */
+declare function summarizeContextRows(rows: readonly ResolvedContextRow[]): {
+    count: number;
+    chars: number;
+    charsLabel: string;
+};
 
 interface ContextRulesChipProps {
     /**
@@ -205,9 +330,16 @@ interface ContextRulesChipProps {
     label?: string | null | undefined;
     rows: readonly ResolvedContextRow[];
     cap: number;
-    /** Page context on/off. Omit when there is no page: the master switch is hidden. */
+    /**
+     * Page context on/off (the face's eye). With no `hierarchy`, also the
+     * header's master switch; with one, the page's switch is its level's
+     * (`hierarchy.masters`) and the header has none.
+     */
     on?: boolean | undefined;
     onToggleAll?: ((next: boolean) => void) | undefined;
+    /** Levels and groups with a switch each (see `ContextRulesTable`). */
+    hierarchy?: ContextHierarchy | null | undefined;
+    onSetInclude?: ((changes: ContextRuleChange[]) => void) | undefined;
     /** False: this turn's model cannot read context — muted face, no amber. */
     modelReadsContext?: boolean | undefined;
     onChange: (key: string, surfaceKey: string, next: SavedContextRule | null) => void;
@@ -223,22 +355,12 @@ interface ContextRulesChipProps {
     onOpenChange?: (open: boolean) => void;
     className?: string;
 }
-/**
- * The header's "N · chars" total. A row whose size is not known yet (an
- * attachment the server has not measured) never counts as 0: with some sizes
- * unknown the total is a floor ("1.2k+"), with none known it is "—".
- */
-declare function summarizeContextRows(rows: readonly ResolvedContextRow[]): {
-    count: number;
-    chars: number;
-    charsLabel: string;
-};
 /**
  * The composer's value-group chip — far right of the composer's one row — and the surface it opens: a header (label,
  * "N · chars" summary, page master switch, reset-all, full view) over the
  * compact rules table. Popover on desktop, bottom sheet on mobile.
  */
-declare function ContextRulesChip({ label, rows, cap, on, onToggleAll, onChange, onResetAll, onOpenFullView, mismatchCount, modelReadsContext, mismatches, onOpenRow, isMobile, readOnly, open: openProp, onOpenChange, className, }: ContextRulesChipProps): react.JSX.Element;
+declare function ContextRulesChip({ label, rows, cap, on, onToggleAll, hierarchy, onSetInclude, onChange, onResetAll, onOpenFullView, mismatchCount, modelReadsContext, mismatches, onOpenRow, isMobile, readOnly, open: openProp, onOpenChange, className, }: ContextRulesChipProps): react.JSX.Element;
 
 interface ContextRulesPanelBodyProps {
     rows: readonly ResolvedContextRow[];
@@ -250,6 +372,9 @@ interface ContextRulesPanelBodyProps {
     loadView?: ContextViewLoader;
     readOnly?: boolean | undefined;
     onChange: (key: string, surfaceKey: string, next: SavedContextRule | null) => void;
+    /** Levels and groups with a switch each (see `ContextRulesTable`). */
+    hierarchy?: ContextHierarchy | null | undefined;
+    onSetInclude?: ((changes: ContextRuleChange[]) => void) | undefined;
     /** Host content under the built-in controls (a value preview, source link…). */
     renderDetail?: (row: ResolvedContextRow) => react.ReactNode;
     isMobile?: boolean;
@@ -263,7 +388,7 @@ interface ContextRulesPanelBodyProps {
  * the left, the open row's controls, layer breakdown and host detail on the
  * right. On mobile: list, then detail with Back.
  */
-declare function ContextRulesPanelBody({ rows, cap, mismatches, blocks, loadView, readOnly, onChange, renderDetail, isMobile, selectedKey: selectedProp, onSelectedKeyChange, className, }: ContextRulesPanelBodyProps): react.JSX.Element;
+declare function ContextRulesPanelBody({ rows, cap, mismatches, blocks, loadView, readOnly, onChange, hierarchy, onSetInclude, renderDetail, isMobile, selectedKey: selectedProp, onSelectedKeyChange, className, }: ContextRulesPanelBodyProps): react.JSX.Element;
 
 interface InlineMaxInputProps {
     /** The person's own limit, or null when inherited. */
@@ -335,4 +460,4 @@ declare function ContextReceiptBlockDetail({ block, load, className, }: {
     className?: string;
 }): react.JSX.Element;
 
-export { ContextDeliveredValue, ContextReceiptBlockDetail, ContextReceiptBlocks, type ContextReceiptBlocksProps, ContextRulesChip, type ContextRulesChipProps, type ContextRulesDensity, ContextRulesPanelBody, type ContextRulesPanelBodyProps, ContextRulesTable, type ContextRulesTableProps, DeliveredSection, InlineMaxInput, type InlineMaxInputProps, summarizeContextRows };
+export { AI_MATRX_LEVEL, ATTACHED_LEVEL, ContextDeliveredValue, type ContextGroupNode, type ContextGroupRef, type ContextHierarchy, type ContextLevelMaster, type ContextLevelNode, type ContextLevelRef, ContextReceiptBlockDetail, ContextReceiptBlocks, type ContextReceiptBlocksProps, type ContextRowPlace, type ContextRuleChange, ContextRulesChip, type ContextRulesChipProps, type ContextRulesDensity, ContextRulesPanelBody, type ContextRulesPanelBodyProps, ContextRulesTable, type ContextRulesTableProps, DeliveredSection, InlineMaxInput, type InlineMaxInputProps, PAGE_LEVEL, buildContextLevels, includeChanges, inheritedInclude, levelRows, placeByOrigin, summarizeContextRows };

package/dist/context/react/index.d.ts

@@ -1,5 +1,19 @@
 import * as react from 'react';
 
+/**
+ * @ai-matrx/agents/context — the context value rules, headless.
+ *
+ * Contract: common-docs/systems/scopes-context/context-delivery/RULES.md.
+ * Parity corpus: ./rules-corpus.json (run here by rules.test.ts and by aidream's
+ * pytest against the Python twin `resolve_context_rule`). Every function here
+ * is pure, zero-React, and safe to import on a server.
+ *
+ * The one flow a client runs per turn:
+ *   rows    = values.map(v => resolveContextRow(v, savedRows, cap))   // what the table shows
+ *   context = buildContextWire(rows)                                   // what the request sends
+ *   …on `context_receipt`: compareReceipt(rows, receipt)               // screen vs server
+ */
+
 /** Which layer decided a field — lowest to highest. */
 type ContextLayer = "default" | "page" | "agent" | "you";
 type ContextDelivery = "inline" | "on_request" | "off";
@@ -173,6 +187,95 @@ interface ContextReceiptMismatch {
     reason?: "self_check";
 }
 
+/**
+ * THE HIERARCHY of the context rules table — where each value sits, and the
+ * switch at every level (Arman, 2026-10-02: "AI Matrx" for the platform's own
+ * values; the page by its section and real name; under it the page's own
+ * declared groups; a switch per level).
+ *
+ * The package never knows a page's groups: the host PLACES each row (level +
+ * group, both already-human labels) and may give a level a host switch (the
+ * page's own on/off). Without a host placement every row is placed by its
+ * origin. A level or group switch is NOT a new kind of rule: it is the
+ * person's per-value include rules for every value in it, written at once
+ * (`includeChanges`), so the server's gate and receipt see exactly the rules
+ * they already honour.
+ */
+
+/** A level of the table: the platform, a page, the chat's attachments. */
+interface ContextLevelRef {
+    /** Stable id (a surface key, `ai_matrx`, `attached`). */
+    id: string;
+    /** Heading, root first: `["Marketing", "Marketing Brand Cockpit"]`, `["AI Matrx"]`. */
+    path: readonly string[];
+    /** Sort order between levels (lower first). */
+    order?: number;
+}
+/** A group inside a level — the page's own declared group, label as declared. */
+interface ContextGroupRef {
+    id: string;
+    label: string;
+    order?: number;
+}
+/** Where one row sits. */
+interface ContextRowPlace {
+    level: ContextLevelRef;
+    /** Null: directly under the level. */
+    group?: ContextGroupRef | null;
+}
+/**
+ * A level whose switch is the host's own (the page on/off for this
+ * conversation) rather than the person's per-value rules. Shown even when the
+ * level has no rows, so the switch never disappears with its values.
+ */
+interface ContextLevelMaster {
+    level: ContextLevelRef;
+    on: boolean;
+    onToggle?: ((next: boolean) => void) | undefined;
+}
+interface ContextHierarchy {
+    place: (row: ResolvedContextRow) => ContextRowPlace;
+    masters?: readonly ContextLevelMaster[];
+}
+interface ContextGroupNode {
+    ref: ContextGroupRef;
+    rows: ResolvedContextRow[];
+}
+interface ContextLevelNode {
+    ref: ContextLevelRef;
+    /** Rows directly under the level (no group). */
+    rows: ResolvedContextRow[];
+    groups: ContextGroupNode[];
+    master: ContextLevelMaster | null;
+}
+/** The platform's own values: the person, their organization, the client. */
+declare const AI_MATRX_LEVEL: ContextLevelRef;
+/** Files and documents attached to the conversation. */
+declare const ATTACHED_LEVEL: ContextLevelRef;
+/** A page the host has not named. */
+declare const PAGE_LEVEL: ContextLevelRef;
+/** The placement a host without one gets: by origin. */
+declare function placeByOrigin(row: ResolvedContextRow): ContextRowPlace;
+/** Rows → levels → groups, in the host's order (stable within equal orders). */
+declare function buildContextLevels(rows: readonly ResolvedContextRow[], hierarchy?: ContextHierarchy | null): ContextLevelNode[];
+/** Every row of a level, groups included. */
+declare function levelRows(level: ContextLevelNode): ResolvedContextRow[];
+/** What the row's include would be with no rule of the person's. */
+declare function inheritedInclude(row: ResolvedContextRow, cap: number): boolean;
+/** One person-rule write: `rule: null` removes the person's rule for that value. */
+interface ContextRuleChange {
+    key: string;
+    surfaceKey: string;
+    rule: SavedContextRule | null;
+}
+/**
+ * A level or group switch: the person's include rule for every value in it
+ * that is not already `include`. A value whose default already gives
+ * `include` loses its own include rule instead (back to the default) — the
+ * saved rules stay minimal and "Reset all" means what it says.
+ */
+declare function includeChanges(rows: readonly ResolvedContextRow[], include: boolean, cap: number): ContextRuleChange[];
+
 type ContextRulesDensity = "compact" | "comfortable";
 interface ContextRulesTableProps {
     rows: readonly ResolvedContextRow[];
@@ -187,13 +290,35 @@ interface ContextRulesTableProps {
     density?: ContextRulesDensity;
     /** Highlights the open row (master/detail). */
     selectedKey?: string | null;
+    /**
+     * Where each row sits (level → group) and the host's level switches. Omit:
+     * rows sit under their origin ("Page", "Attached", "AI Matrx").
+     */
+    hierarchy?: ContextHierarchy | null | undefined;
+    /**
+     * A level or group switch: the person's per-value rules for every value in
+     * it, at once. Omit: level and group switches are hidden (a host master
+     * switch still shows).
+     */
+    onSetInclude?: ((changes: ContextRuleChange[]) => void) | undefined;
     className?: string;
 }
 /**
  * The context rules table: Item | Include | Chars | Inline max. Presentational
  * and state-agnostic — every edit goes out through `onChange`.
  */
-declare function ContextRulesTable({ rows, cap, readOnly, mismatches, onChange, onOpenRow, density, selectedKey, className, }: ContextRulesTableProps): react.JSX.Element;
+declare function ContextRulesTable({ rows, cap, readOnly, mismatches, onChange, onOpenRow, density, selectedKey, hierarchy, onSetInclude, className, }: ContextRulesTableProps): react.JSX.Element;
+
+/**
+ * The header's "N · chars" total. A row whose size is not known yet (an
+ * attachment the server has not measured) never counts as 0: with some sizes
+ * unknown the total is a floor ("1.2k+"), with none known it is "—".
+ */
+declare function summarizeContextRows(rows: readonly ResolvedContextRow[]): {
+    count: number;
+    chars: number;
+    charsLabel: string;
+};
 
 interface ContextRulesChipProps {
     /**
@@ -205,9 +330,16 @@ interface ContextRulesChipProps {
     label?: string | null | undefined;
     rows: readonly ResolvedContextRow[];
     cap: number;
-    /** Page context on/off. Omit when there is no page: the master switch is hidden. */
+    /**
+     * Page context on/off (the face's eye). With no `hierarchy`, also the
+     * header's master switch; with one, the page's switch is its level's
+     * (`hierarchy.masters`) and the header has none.
+     */
     on?: boolean | undefined;
     onToggleAll?: ((next: boolean) => void) | undefined;
+    /** Levels and groups with a switch each (see `ContextRulesTable`). */
+    hierarchy?: ContextHierarchy | null | undefined;
+    onSetInclude?: ((changes: ContextRuleChange[]) => void) | undefined;
     /** False: this turn's model cannot read context — muted face, no amber. */
     modelReadsContext?: boolean | undefined;
     onChange: (key: string, surfaceKey: string, next: SavedContextRule | null) => void;
@@ -223,22 +355,12 @@ interface ContextRulesChipProps {
     onOpenChange?: (open: boolean) => void;
     className?: string;
 }
-/**
- * The header's "N · chars" total. A row whose size is not known yet (an
- * attachment the server has not measured) never counts as 0: with some sizes
- * unknown the total is a floor ("1.2k+"), with none known it is "—".
- */
-declare function summarizeContextRows(rows: readonly ResolvedContextRow[]): {
-    count: number;
-    chars: number;
-    charsLabel: string;
-};
 /**
  * The composer's value-group chip — far right of the composer's one row — and the surface it opens: a header (label,
  * "N · chars" summary, page master switch, reset-all, full view) over the
  * compact rules table. Popover on desktop, bottom sheet on mobile.
  */
-declare function ContextRulesChip({ label, rows, cap, on, onToggleAll, onChange, onResetAll, onOpenFullView, mismatchCount, modelReadsContext, mismatches, onOpenRow, isMobile, readOnly, open: openProp, onOpenChange, className, }: ContextRulesChipProps): react.JSX.Element;
+declare function ContextRulesChip({ label, rows, cap, on, onToggleAll, hierarchy, onSetInclude, onChange, onResetAll, onOpenFullView, mismatchCount, modelReadsContext, mismatches, onOpenRow, isMobile, readOnly, open: openProp, onOpenChange, className, }: ContextRulesChipProps): react.JSX.Element;
 
 interface ContextRulesPanelBodyProps {
     rows: readonly ResolvedContextRow[];
@@ -250,6 +372,9 @@ interface ContextRulesPanelBodyProps {
     loadView?: ContextViewLoader;
     readOnly?: boolean | undefined;
     onChange: (key: string, surfaceKey: string, next: SavedContextRule | null) => void;
+    /** Levels and groups with a switch each (see `ContextRulesTable`). */
+    hierarchy?: ContextHierarchy | null | undefined;
+    onSetInclude?: ((changes: ContextRuleChange[]) => void) | undefined;
     /** Host content under the built-in controls (a value preview, source link…). */
     renderDetail?: (row: ResolvedContextRow) => react.ReactNode;
     isMobile?: boolean;
@@ -263,7 +388,7 @@ interface ContextRulesPanelBodyProps {
  * the left, the open row's controls, layer breakdown and host detail on the
  * right. On mobile: list, then detail with Back.
  */
-declare function ContextRulesPanelBody({ rows, cap, mismatches, blocks, loadView, readOnly, onChange, renderDetail, isMobile, selectedKey: selectedProp, onSelectedKeyChange, className, }: ContextRulesPanelBodyProps): react.JSX.Element;
+declare function ContextRulesPanelBody({ rows, cap, mismatches, blocks, loadView, readOnly, onChange, hierarchy, onSetInclude, renderDetail, isMobile, selectedKey: selectedProp, onSelectedKeyChange, className, }: ContextRulesPanelBodyProps): react.JSX.Element;
 
 interface InlineMaxInputProps {
     /** The person's own limit, or null when inherited. */
@@ -335,4 +460,4 @@ declare function ContextReceiptBlockDetail({ block, load, className, }: {
     className?: string;
 }): react.JSX.Element;
 
-export { ContextDeliveredValue, ContextReceiptBlockDetail, ContextReceiptBlocks, type ContextReceiptBlocksProps, ContextRulesChip, type ContextRulesChipProps, type ContextRulesDensity, ContextRulesPanelBody, type ContextRulesPanelBodyProps, ContextRulesTable, type ContextRulesTableProps, DeliveredSection, InlineMaxInput, type InlineMaxInputProps, summarizeContextRows };
+export { AI_MATRX_LEVEL, ATTACHED_LEVEL, ContextDeliveredValue, type ContextGroupNode, type ContextGroupRef, type ContextHierarchy, type ContextLevelMaster, type ContextLevelNode, type ContextLevelRef, ContextReceiptBlockDetail, ContextReceiptBlocks, type ContextReceiptBlocksProps, type ContextRowPlace, type ContextRuleChange, ContextRulesChip, type ContextRulesChipProps, type ContextRulesDensity, ContextRulesPanelBody, type ContextRulesPanelBodyProps, ContextRulesTable, type ContextRulesTableProps, DeliveredSection, InlineMaxInput, type InlineMaxInputProps, PAGE_LEVEL, buildContextLevels, includeChanges, inheritedInclude, levelRows, placeByOrigin, summarizeContextRows };