@stndrds/schema 1.0.0-alpha.265 → 1.0.0-alpha.267

package/dist/index-DtxtOBYT.d.mts

@@ -0,0 +1,2413 @@
+import { z } from 'zod';
+import { A as Attribute, f as AttributeType, e as RollupAttribute } from './attributes-lBLiOIY3.mjs';
+import { IconName, MimeType } from '@stndrds/constants';
+import { Uuid } from './utils.mjs';
+import { L as ListViewTabVisibility, T as Timestamps, R as ResourceVisibility } from './objects-BCaBw2ef.mjs';
+
+/** Operators for text-based attributes */
+type TextFilterOperator = "is" | "is_not" | "contains" | "not_contains" | "starts_with" | "ends_with" | "is_empty" | "is_not_empty";
+/** Operators for number-based attributes */
+type NumberFilterOperator = "is" | "is_not" | "less_than" | "greater_than" | "less_or_equal" | "greater_or_equal" | "is_empty" | "is_not_empty";
+/** Operators for checkbox — `is` with a boolean rule value (a checkbox always has a value) */
+type CheckboxFilterOperator = "is";
+/** Operators for date-based attributes (ordering shares the numeric vocabulary) */
+type DateFilterOperator = "is" | "is_not" | "less_than" | "greater_than" | "less_or_equal" | "greater_or_equal" | "is_within" | "on_day_month" | "is_empty" | "is_not_empty";
+/** Operators for select-based attributes (supports single or multi-value filtering) */
+type SelectFilterOperator = "is" | "is_not" | "any_of" | "none_of" | "is_empty" | "is_not_empty";
+/** Operators for multiselect-based attributes — set membership only */
+type MultiselectFilterOperator = "any_of" | "none_of" | "is_empty" | "is_not_empty";
+/**
+ * Operators for relation-based attributes (covers single, multi-value, and
+ * reference-shaped filtering — user, relation, document share the same
+ * edge-backed operator set). Membership is `any_of`/`none_of` only.
+ */
+type RelationFilterOperator = "is" | "is_not" | "any_of" | "none_of" | "is_empty" | "is_not_empty";
+/**
+ * All possible filter operators — the canonical set of 16.
+ * Short input codes (`lt`, `gte`, `eq`, `in`, …) are accepted at entry only
+ * and normalized via SYNONYM_ALIASES; they are never stored and never typed.
+ */
+type FilterOperator = TextFilterOperator | NumberFilterOperator | CheckboxFilterOperator | DateFilterOperator | SelectFilterOperator | MultiselectFilterOperator | RelationFilterOperator;
+/** Relative date value for "is_within" operator */
+interface RelativeDateValue {
+    amount: number;
+    unit: "days" | "weeks" | "months" | "years";
+    direction: "past" | "future";
+}
+/** Currency filter value with amount and optional currency codes
+ * - code: undefined or [] = any currency
+ * - code: string[] = filter by specific currencies
+ */
+interface CurrencyFilterValue {
+    value: number | null;
+    code?: string[];
+}
+/** Phone filter value with number and optional country code */
+interface PhoneFilterValue {
+    phoneNumber: string | null;
+    countryCode?: string;
+}
+/**
+ * A filter value resolved at query time from the execution context.
+ * Stored verbatim in a view's filter; replaced with a concrete value by the
+ * runtime before reaching any query layer. Discriminated by the `dynamic` key —
+ * no static FilterValue carries it.
+ */
+type DynamicValue = {
+    dynamic: "actor";
+    ref: "current";
+} | {
+    dynamic: "date";
+    anchor: "today";
+} | {
+    dynamic: "date";
+    anchor: "now";
+};
+/** Filter value can be various types depending on the attribute */
+type FilterValue = string | number | boolean | string[] | RelativeDateValue | CurrencyFilterValue | PhoneFilterValue | DynamicValue | null;
+/** Existence quantifier for qualified edge rules. Maps to SQL EXISTS / NOT EXISTS. */
+type EdgeQuantifier = "any" | "none";
+/** A single filter rule */
+interface FilterRule {
+    /** Root attribute name (scalar attribute, or a reference attribute when `property` is set). */
+    attribute: string;
+    /**
+     * If set, this rule filters on a qualified edge property.
+     * Requires `attribute` to be a reference attribute (today: `relation` or `document`) that has `.qualifyWith()`.
+     * The `operator` must be valid for the property's type, not the root attribute's type.
+     */
+    property?: string;
+    /**
+     * Existence quantifier for qualified edge rules ("at least one" vs "none").
+     * Only valid when `property` is set. Maps to SQL EXISTS / NOT EXISTS.
+     * Defaults to the operator-derived polarity when omitted.
+     */
+    quantifier?: EdgeQuantifier;
+    /** Filter operator */
+    operator: FilterOperator;
+    /** Filter value (null for operators like is_empty) */
+    value: FilterValue;
+}
+/**
+ * Extended filter rule with optional attribute definition.
+ * When provided, enables smarter type-aware filtering (e.g., array operators for multiselect).
+ */
+interface ExtendedFilterRule extends FilterRule {
+    /** Full attribute definition for type-aware filtering */
+    attributeDef?: Attribute;
+}
+/** Combinator for filter rules */
+type FilterCombinator = "and" | "or";
+/** Complete filter state (simple mode) */
+interface FilterState {
+    /** How to combine rules */
+    combinator: FilterCombinator;
+    /** List of filter rules */
+    rules: FilterRule[];
+}
+/**
+ * A filter group containing rules (used in advanced mode)
+ * Groups can be nested up to 2 levels deep
+ */
+interface FilterGroup {
+    /** Unique identifier for this group */
+    id: string;
+    /** How to combine rules within this group */
+    combinator: FilterCombinator;
+    /** List of filter rules in this group */
+    rules: FilterRule[];
+}
+/**
+ * Advanced filter state with nested groups
+ * Structure: AdvancedFilterState -> FilterGroup[] -> FilterRule[]
+ * Maximum 2 levels of nesting
+ */
+interface AdvancedFilterState {
+    /** How to combine groups at the top level */
+    combinator: FilterCombinator;
+    /** List of filter groups */
+    groups: FilterGroup[];
+}
+/** Sort direction */
+type SortDirection = "asc" | "desc";
+/** A single sort rule */
+interface SortRule {
+    /** Attribute name to sort by */
+    attribute: string;
+    /** Sort direction */
+    direction: SortDirection;
+}
+/** Complete query state with search, filters, sorts, and pagination */
+interface QueryState {
+    /** Full-text search query */
+    search?: string;
+    /** Filter configuration (simple mode) */
+    filters?: FilterState;
+    /** Advanced filter configuration (grouped mode) */
+    advancedFilters?: AdvancedFilterState;
+    /** Sort configuration (multiple sorts supported) */
+    sorts?: SortRule[];
+    /** Pagination */
+    limit?: number;
+    offset?: number;
+}
+/** Mapping of attribute types to their valid operators (rollup excluded — use getRollupFilterOperators()) */
+declare const OPERATORS_BY_TYPE: Record<Exclude<AttributeType, "rollup">, readonly FilterOperator[]>;
+/** Check if an operator requires a value */
+type NoValueOperator = "is_empty" | "is_not_empty";
+/** Operators that don't require a value */
+declare const NO_VALUE_OPERATORS: readonly NoValueOperator[];
+/**
+ * Check if an operator requires a value
+ */
+declare function isNoValueOperator(operator: FilterOperator): operator is NoValueOperator;
+/**
+ * Get the filter operators for a rollup attribute based on its aggregation function and target type.
+ *
+ * - earliest / latest → date operators
+ * - original → operators matching targetAttributeType (falls back to numeric if unknown)
+ * - all other functions → numeric operators (sum, avg, count, percent, etc.)
+ */
+declare function getRollupFilterOperators(attr: RollupAttribute): readonly FilterOperator[];
+
+/**
+ * Type of view - determines the config structure
+ */
+type ViewType = "detail" | "list";
+/**
+ * Creation behavior when clicking the "+" button
+ * - `redirect`: Create the record then navigate to its detail page
+ * - `inline`: Insert an empty row in the table (no navigation)
+ * - `peek`: Create a draft immediately and open it in the record stack side panel
+ */
+type CreateMode = "redirect" | "inline" | "peek";
+/**
+ * Inline attribute group configuration
+ * Groups multiple attributes into a single composite field with dropdown editing
+ */
+interface AttributeGroupField {
+    /** Unique identifier for the group */
+    id: string;
+    /** Display label for the composite field */
+    label: string;
+    /** Description shown in the dropdown */
+    description?: string;
+    /** Attribute names to include in this group */
+    attributes: string[];
+    /**
+     * Template for the display value
+     * Uses {attributeName} syntax for interpolation
+     * @example "{billing_street}, {billing_city} {billing_postal_code}"
+     */
+    displayTemplate?: string;
+}
+/**
+ * Field definition within a form group
+ * Can be either a single attribute or an inline attribute group
+ */
+interface Field {
+    /** Attribute name to display (for single attribute fields) */
+    attribute?: string;
+    /** Inline attribute group (groups multiple attributes into one composite field) */
+    attributeGroup?: AttributeGroupField;
+    /** Grid span (1-12 columns) */
+    span?: 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12;
+    /** Override label for this view (only for single attribute fields) */
+    label?: string;
+    /** Force read-only display */
+    readOnly?: boolean;
+}
+/**
+ * Base properties shared by all group types
+ */
+interface BaseGroup {
+    id: string;
+    label: string;
+    description?: string;
+    collapsible?: boolean;
+    collapsed?: boolean;
+    order?: number;
+}
+/**
+ * Group of fields for organizing forms (default group type)
+ */
+interface FieldGroup extends BaseGroup {
+    /** Discriminant */
+    type: "fields";
+    fields: Field[];
+}
+/**
+ * Group that displays related records for a relation attribute
+ */
+interface RelationGroup extends BaseGroup {
+    type: "relation";
+    /** Relation attribute name on the source object */
+    attribute: string;
+    /** Columns to display (auto-detected from target object if empty) */
+    columns?: string[];
+    /** Read-only mode */
+    readOnly?: boolean;
+    /** Allow creating new related records */
+    allowCreate?: boolean;
+}
+/**
+ * Discriminated union of all group types
+ */
+type Group = FieldGroup | RelationGroup;
+type TabType = "form" | "table" | "custom" | "activity" | "richtext" | "documents" | "forms" | "emails";
+/**
+ * Base properties shared by all tab types
+ */
+interface BaseTab {
+    id: string;
+    name: string;
+    label: string;
+    icon?: IconName;
+    order?: number;
+}
+/**
+ * Form layout density
+ */
+type FormDensity = "compact" | "comfortable" | "spacious";
+/**
+ * Form tab - displays attributes organized in groups
+ */
+interface FormTab extends BaseTab {
+    type: "form";
+    groups: Group[];
+    /** Number of grid columns (1, 2, or 3). Default: 2 */
+    formColumns?: 1 | 2 | 3;
+    /** Layout density. Default: "comfortable" */
+    density?: FormDensity;
+}
+/**
+ * Direct relation on the current object
+ *
+ * @example Contact.companies → shows Companies linked via the "companies" relation
+ */
+interface RelationSource {
+    type: "relation";
+    /** Relation attribute name on the current object */
+    attribute: string;
+}
+/**
+ * Inverse lookup — records from another object that point to us
+ *
+ * @example On Company, show Contacts where Contact.company = this Company
+ */
+interface InverseSource {
+    type: "inverse";
+    /** Object name that has the relation to us */
+    object: string;
+    /** Relation attribute name on the source object that points to us */
+    attribute: string;
+}
+/**
+ * Where table data comes from — either a direct relation or an inverse lookup
+ */
+type TableSource = RelationSource | InverseSource;
+/**
+ * Table tab - displays related records in a table
+ *
+ * The `source` field determines where data comes from.
+ *
+ * @example Direct: source = { type: "relation", attribute: "members" }
+ * @example Inverse: source = { type: "inverse", object: "contacts", attribute: "company" }
+ */
+interface TableTab extends BaseTab {
+    type: "table";
+    /** Where the data comes from */
+    source: TableSource;
+    /** Columns to display (attribute names from the resolved target object) */
+    columns: string[];
+    /** Allow creating new records */
+    allowCreate?: boolean;
+    /** Creation behavior when allowCreate is true. Default: "redirect" */
+    createMode?: CreateMode;
+    /** Allow inline editing */
+    allowEdit?: boolean;
+    /** Allow deleting records */
+    allowDelete?: boolean;
+    /** Default filters applied to the table */
+    filters?: FilterState;
+    /** Default sort rules */
+    sorts?: SortRule[];
+}
+/**
+ * Custom tab - renders a developer-defined component
+ */
+interface CustomTab extends BaseTab {
+    type: "custom";
+    /** Component identifier to render */
+    component: string;
+    /** Props to pass to the component */
+    props?: Record<string, unknown>;
+}
+/**
+ * Activity tab - displays activity feed for the current record
+ */
+interface ActivityTab extends BaseTab {
+    type: "activity";
+    limit?: number;
+}
+/**
+ * Richtext tab - displays a block editor for a richtext attribute
+ */
+interface RichtextTab extends BaseTab {
+    type: "richtext";
+    /** Richtext attribute to display in the BlockEditor */
+    attribute: string;
+    /** Optional text attribute for an editable title input above the editor */
+    titleAttribute?: string;
+}
+/**
+ * Documents tab - displays all documents attached to the record
+ */
+interface DocumentsTab extends BaseTab {
+    type: "documents";
+    allowUpload?: boolean;
+    allowRemove?: boolean;
+    hideAttachments?: boolean;
+}
+/**
+ * Forms tab - displays available forms for creating related records
+ */
+interface FormsTab extends BaseTab {
+    type: "forms";
+    /** Object name to filter forms by slot (derived from record context, but can be overridden) */
+    objectName?: string;
+}
+/**
+ * Emails tab - displays emails associated with the record at query time via the
+ * values of configured email-bearing text attributes. Config-only: no schema change.
+ */
+interface EmailsTab extends BaseTab {
+    type: "emails";
+    /** Names of text attributes whose values hold email addresses to match on. */
+    emailAttributeIds: string[];
+}
+/**
+ * Union of all tab types (for detail views)
+ */
+type Tab = FormTab | TableTab | CustomTab | ActivityTab | RichtextTab | DocumentsTab | FormsTab | EmailsTab;
+/**
+ * List view layout mode
+ * - `table`: Table/grid layout
+ * - `kanban`: Kanban board layout (grouped by attribute)
+ */
+type ListViewLayout = "table" | "kanban";
+/**
+ * Tab within a list view — each tab carries its own full display configuration.
+ *
+ * @example
+ * ```typescript
+ * const tabs: ListViewTab[] = [
+ *   { id: "all", label: "All Contacts", default: true, visibility: "workspace", layout: "table", columns: ["name", "email", "status"] },
+ *   { id: "active", label: "Active", visibility: "workspace", layout: "table", columns: ["name", "email"], filters: activeFilter },
+ *   { id: "pipeline", label: "Pipeline", visibility: "workspace", layout: "kanban", columns: ["name", "amount"], groupByAttribute: "stage" },
+ * ];
+ * ```
+ */
+interface ListViewTab {
+    /** Unique identifier */
+    id: string;
+    /** Display label */
+    label: string;
+    /** Icon */
+    icon?: IconName;
+    /** Default tab (shown on load) */
+    default?: boolean;
+    /**
+     * Record scope this tab reads. `all` (the default) imposes no scope, so the
+     * tab shows every workspace record plus the viewer's own private ones;
+     * `workspace` and `private` narrow it to exactly one.
+     */
+    visibility: ListViewTabVisibility;
+    /** Layout mode */
+    layout: ListViewLayout;
+    /** Attribute names to display as columns */
+    columns: string[];
+    /** Column widths in pixels */
+    columnSizing?: Record<string, number>;
+    /** Filters applied to this tab */
+    filters?: FilterGroup;
+    /** Sort rules for this tab */
+    sorts?: SortRule[];
+    /** Attribute to group by (required when layout is "kanban") */
+    groupByAttribute?: string;
+    /** When true, the tab is read-only: no cell editing, no create, no delete */
+    readOnly?: boolean;
+    /** Creation behavior when clicking "+". Default: "redirect" */
+    createMode?: CreateMode;
+    /** User attribute to display on kanban cards (bottom-left) */
+    cardUserAttribute?: string;
+    /** Date attribute to display on kanban cards (bottom-right) */
+    cardDateAttribute?: string;
+    /** Order of kanban columns (by option value) - for kanban layout only */
+    kanbanColumnOrder?: string[];
+    /** Visibility of kanban columns (by option value) - for kanban layout only */
+    kanbanColumnVisibility?: Record<string, boolean>;
+    /** Pinned kanban columns (by option value) - for kanban layout only */
+    kanbanPinnedColumns?: string[];
+}
+/**
+ * Configuration for the side panel displayed alongside tab content.
+ * When present, a right-side panel shows the configured attributes as flat fields.
+ */
+interface SidePanelConfig {
+    /** Attribute names to display as flat fields in the panel */
+    attributes: string[];
+    /** Width in pixels. @default 320 */
+    width?: number;
+}
+/**
+ * Configuration for detail views (RecordEditView)
+ */
+interface DetailViewConfig {
+    /** Tabs in this view */
+    tabs: Tab[];
+    /** Optional side panel with flat attribute fields */
+    sidePanel?: SidePanelConfig;
+}
+/**
+ * Configuration for list views (RecordsView)
+ *
+ * Each tab carries its own full config (layout, columns, filters, sorts, groupBy).
+ * The view only holds shared base filters applied to ALL tabs.
+ */
+interface ListViewConfig {
+    /** Base filters applied to ALL tabs (scoping, tenant, etc.) */
+    defaultFilters?: FilterGroup;
+    /** Tabs — at least one required. Each carries its own full config. */
+    tabs: ListViewTab[];
+}
+/**
+ * Union of all view configs
+ */
+type ViewConfig = DetailViewConfig | ListViewConfig;
+/**
+ * Base view properties shared by all view types
+ */
+interface BaseViewDefinition {
+    /** Unique identifier (UUID, assigned by database) */
+    id?: string;
+    /** Technical name (kebab-case) */
+    name: string;
+    /** Display label */
+    label: string;
+    /** Description */
+    description?: string;
+    /** Icon */
+    icon?: IconName;
+    /** Object this view belongs to (object name) */
+    object: string;
+    /** Default view for this object+type combination */
+    default?: boolean;
+    /** Extensible metadata */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Detail view definition
+ */
+interface DetailViewDefinition extends BaseViewDefinition {
+    type: "detail";
+    config: DetailViewConfig;
+}
+/**
+ * List view definition
+ */
+interface ListViewDefinition extends BaseViewDefinition {
+    type: "list";
+    config: ListViewConfig;
+}
+/**
+ * Unified view definition - discriminated union by type
+ */
+type ViewDefinition = DetailViewDefinition | ListViewDefinition;
+/**
+ * Configuration overrides for user customizations
+ * Only stores the delta from the source view
+ */
+interface ConfigOverrides {
+    tabs?: ListViewTab[];
+    hiddenTabIds?: string[];
+    detailTabs?: Tab[];
+    hiddenDetailTabIds?: string[];
+}
+/**
+ * User customization overlay for a view
+ * Stored per user, merged at runtime with the source view
+ */
+interface ViewOverlay {
+    /** Unique identifier */
+    id: string;
+    /** View ID this overlay applies to (UUID or virtual ID) */
+    viewId: string;
+    /** User ID who owns this overlay */
+    userId: string;
+    /** Configuration overrides (delta only) */
+    configOverrides: ConfigOverrides;
+    /** User's default view for this object (stored in overlay) */
+    isUserDefault?: boolean;
+    /** Created timestamp */
+    createdAt: Date;
+    /** Updated timestamp */
+    updatedAt: Date;
+}
+/**
+ * Check if a view is a detail view
+ */
+declare function isDetailView(view: ViewDefinition): view is DetailViewDefinition;
+/**
+ * Check if a view is a list view
+ */
+declare function isListView(view: ViewDefinition): view is ListViewDefinition;
+/**
+ * Check if a group is a field group (default type)
+ */
+declare function isFieldGroup(group: Group): group is FieldGroup;
+/**
+ * Check if a group is a relation group
+ */
+declare function isRelationGroup(group: Group): group is RelationGroup;
+
+/**
+ * Scope of a permission rule.
+ * - `object`: Controls access to an entire object type (business data)
+ * - `system`: Controls access to platform resources (people, workspace, API keys, etc.)
+ */
+type PermissionScope = "object" | "system";
+/**
+ * Actions that can be performed on a resource.
+ *
+ * `observe` is intentionally excluded from `ALL_ACTIONS` ("full" preset) — it
+ * is only meaningful for runnable resources (agent sessions) where it grants
+ * read-only visibility on the run timeline without implying CRUD.
+ */
+type Action = "read" | "create" | "update" | "delete" | "manage" | "observe";
+/**
+ * System resources that can be managed.
+ * - `people`: User profiles, invitations, roles and permissions
+ * - `workspace`: Tenant settings and workspace-level configuration
+ * - `architect`: Architect settings, templates, and configurations
+ */
+type SystemResource = "people" | "workspace" | "architect" | "feature-flags" | "files" | "views" | "forms" | "documents" | "audit" | "api-keys" | "connectors" | "env-vars" | "session";
+/**
+ * Preset access levels for simplified permission configuration.
+ * - `full`: All CRUD actions
+ * - `read-only`: Only read action
+ * - `none`: No actions
+ * - `custom`: Manual selection of individual actions
+ */
+type AccessLevel = "full" | "read-only" | "none" | "custom";
+declare const ALL_ACTIONS: Action[];
+/**
+ * Derive an AccessLevel from a list of actions.
+ */
+declare function actionsToAccessLevel(actions: Action[]): AccessLevel;
+/**
+ * Convert an AccessLevel preset to its corresponding actions.
+ */
+declare function accessLevelToActions(level: Exclude<AccessLevel, "custom">): Action[];
+/**
+ * Role definition - Groups permissions together.
+ *
+ * Roles are tenant-scoped and can be system-defined (immutable) or custom.
+ *
+ * @example
+ * ```typescript
+ * const ownerRole: Role = {
+ *   id: "role-123",
+ *   tenantId: "tenant-456",
+ *   name: "owner",
+ *   label: "Owner",
+ *   description: "Full access to all platform features and data",
+ *   system: true,
+ *   createdAt: new Date(),
+ *   updatedAt: new Date(),
+ * };
+ * ```
+ */
+interface Role extends Timestamps {
+    id: Uuid;
+    tenantId: Uuid;
+    /**
+     * Technical name (unique per tenant, used in code).
+     * Examples: "owner", "member", "sales_manager"
+     */
+    name: string;
+    /**
+     * Display name shown in UI.
+     */
+    label: string;
+    /**
+     * Optional description of the role's purpose.
+     */
+    description?: string;
+    /**
+     * If true, this role cannot be modified or deleted.
+     * Used for built-in roles like "owner".
+     */
+    system: boolean;
+}
+/**
+ * Permission definition - Grants specific actions on a target.
+ *
+ * A permission belongs to a role and defines what actions are allowed
+ * on a specific target (object or system resource).
+ *
+ * @example
+ * ```typescript
+ * // Allow read and update on companies object
+ * const permission: Permission = {
+ *   id: "perm-123",
+ *   roleId: "role-456",
+ *   scope: "object",
+ *   target: "companies",
+ *   actions: ["read", "update"],
+ *   createdAt: new Date(),
+ * };
+ *
+ * // Wildcard permission for all objects
+ * const wildcardPerm: Permission = {
+ *   id: "perm-789",
+ *   roleId: "role-456",
+ *   scope: "object",
+ *   target: "*",
+ *   actions: ["read", "create", "update", "delete"],
+ *   createdAt: new Date(),
+ * };
+ * ```
+ */
+interface Permission {
+    id: Uuid;
+    roleId: Uuid;
+    /**
+     * Scope of this permission.
+     */
+    scope: PermissionScope;
+    /**
+     * Target of the permission.
+     * - For `object` scope: object name (e.g., "companies") or "*" for all
+     * - For `system` scope: system resource (e.g., "people", "workspace") or "*" for all
+     */
+    target: string;
+    /**
+     * Actions allowed on the target.
+     */
+    actions: Action[];
+    createdAt: Date;
+}
+/**
+ * Links a user profile to a role within a tenant.
+ *
+ * A user can have multiple roles, and their permissions are additive (union).
+ *
+ * Note: `userProfileId` references UserProfile.id from the user_profiles table,
+ * NOT the auth provider ID (authId). This keeps permissions tied to the
+ * application's user management, not the authentication layer.
+ */
+interface UserRoleAssignment {
+    id: Uuid;
+    /**
+     * User profile ID (UserProfile.id from user_profiles table).
+     * This links to the application's user management system,
+     * not the auth provider's user ID.
+     */
+    userProfileId: Uuid;
+    roleId: Uuid;
+    tenantId: Uuid;
+    /**
+     * When the role was assigned.
+     */
+    assignedAt: Date;
+    /**
+     * Actor ID of who assigned this role (for audit trail).
+     */
+    assignedBy?: Uuid;
+}
+/**
+ * Computed permissions for a user.
+ *
+ * This is the merged result of all roles assigned to a user.
+ * Returned by the API for permission checks.
+ */
+interface EffectivePermissions {
+    /**
+     * Object-level permissions.
+     * Key is the object name, value is array of allowed actions.
+     * Special key "*" means permission applies to all objects.
+     */
+    objectPermissions: Record<string, Action[]>;
+    /**
+     * System-level permissions.
+     * Key is the system resource (people, workspace), value is array of allowed actions.
+     * Special key "*" means permission applies to all system resources.
+     */
+    systemPermissions: Record<string, Action[]>;
+}
+/**
+ * Permissions for a specific object.
+ * Convenience type for frontend use.
+ */
+interface ObjectPermissions {
+    canRead: boolean;
+    canCreate: boolean;
+    canUpdate: boolean;
+    canDelete: boolean;
+    canManage: boolean;
+}
+/**
+ * Permissions for a specific system resource.
+ * Convenience type for frontend use.
+ */
+interface SystemPermissions {
+    canRead: boolean;
+    canCreate: boolean;
+    canUpdate: boolean;
+    canDelete: boolean;
+    canManage: boolean;
+}
+/**
+ * Input for creating a new role.
+ * TenantId is automatically set from TenantContext.
+ */
+interface CreateRoleInput {
+    name: string;
+    label: string;
+    description?: string;
+    /** Framework-owned default roles are system:true (immutable, auto-assignable). Custom roles default false. */
+    system?: boolean;
+}
+/**
+ * Input for updating an existing role.
+ */
+interface UpdateRoleInput {
+    label?: string;
+    description?: string;
+}
+/**
+ * Input for creating a permission.
+ */
+interface CreatePermissionInput {
+    scope: PermissionScope;
+    target: string;
+    /**
+     * Actions allowed on the target.
+     */
+    actions: Action[];
+}
+/**
+ * Input for assigning a role to a user.
+ */
+interface AssignRoleInput {
+    /**
+     * User profile ID (UserProfile.id).
+     */
+    userProfileId: Uuid;
+    roleId: Uuid;
+    tenantId: Uuid;
+    assignedBy?: Uuid;
+}
+
+/**
+ * Type of mentionable entity
+ */
+type MentionEntityType = "user" | "record" | (string & {});
+/**
+ * A mention reference stored with a message
+ */
+interface MentionReference {
+    /** Unique ID for this mention instance */
+    id: string;
+    /** Entity type (user, record, or custom) */
+    type: MentionEntityType;
+    /** Entity ID (user ID or record ID) */
+    entityId: string;
+    /** Display label at time of mention (cached for display even if entity is deleted) */
+    label: string;
+    /** Object name for records, undefined for users */
+    objectName?: string;
+    /** Start position in the message text */
+    startIndex: number;
+    /** End position in the message text */
+    endIndex: number;
+}
+/**
+ * Context data for a mentioned entity (sent to AI)
+ */
+interface MentionedEntityContext {
+    /** Entity type */
+    type: MentionEntityType;
+    /** Entity ID */
+    entityId: string;
+    /** Display label */
+    label: string;
+    /** Object name for records */
+    objectName?: string;
+    /** Additional context data (record values, user details, etc.) */
+    data?: Record<string, unknown>;
+}
+/**
+ * Full mention context for AI
+ */
+interface MentionedContext {
+    /** All mentioned entities with their context data */
+    entities: MentionedEntityContext[];
+    /** Summary text for AI system prompt */
+    summary: string;
+}
+
+type DocumentKind = "file" | "folder";
+interface Document extends Timestamps {
+    id: Uuid;
+    tenantId: Uuid;
+    title: string;
+    kind: DocumentKind;
+    parentId?: Uuid | null;
+    description?: string;
+    contentHash?: string;
+    createdBy?: Uuid;
+    updatedBy?: Uuid;
+    deletedAt?: Date | null;
+    /**
+     * Fractional ordering position within `(tenantId, parentId)`. Lower values
+     * sort first. New rows default to `max(siblings) + 1024` so reorderings can
+     * insert between neighbours without renumbering. The server may rebalance
+     * positions in the background to keep the spacing bounded.
+     */
+    position: number;
+}
+interface DocumentWithSubCount extends Document {
+    subCount: number | null;
+}
+/** OCR processing lifecycle for a single file within a document pack. */
+type FileOcrStatus = "pending" | "processing" | "completed" | "failed";
+/**
+ * A single anonymous file belonging to a document pack.
+ * Unlike the slot-based model, files carry no slot name — order within the
+ * pack is `position` only, and `name` is provenance (originalName), never a
+ * label rendered in the UI.
+ */
+interface DocumentFile {
+    id: Uuid;
+    documentId: Uuid;
+    position: number;
+    /** Provenance only (originalName) — never rendered as a label. */
+    name: string;
+    mimeType: string;
+    size: number;
+    ocrStatus: FileOcrStatus | null;
+    ocrText: string | null;
+    ocrConfidence: number | null;
+    processedAt: Date | null;
+}
+type DocumentWithFiles = Document & {
+    files: DocumentFile[];
+};
+interface CreateDocument {
+    title: string;
+    kind?: DocumentKind;
+    parentId?: Uuid | null;
+    description?: string;
+    position?: number;
+}
+/**
+ * Reference to a record attribute that should atomically attach a freshly
+ * created Document. Passed alongside `CreateDocument` to make creation
+ * link-aware end-to-end (client → REST → service → repo).
+ *
+ * The server requires this — orphan Documents are not creatable through the
+ * REST API.
+ */
+interface CreateDocumentLink {
+    objectName: string;
+    sourceRecordId: string;
+    attributeName: string;
+}
+interface UpdateDocument {
+    title?: string;
+    parentId?: Uuid | null;
+    position?: number;
+}
+interface DocumentListOptions {
+    limit?: number;
+    offset?: number;
+}
+interface RecordDocuments {
+    /** Documents grouped by attribute name (includes system 'attachments' attribute) */
+    byAttribute: Record<string, DocumentWithFiles[]>;
+}
+
+/**
+ * Storage provider type
+ */
+type StorageProvider = "s3" | "gcs" | "azure" | "local" | "cloudflare-r2" | string;
+/**
+ * File - Represents uploaded file metadata and storage info
+ *
+ * ARCHITECTURE:
+ * - Fixed table (no custom attributes)
+ * - Manages file storage metadata
+ * - uploadedBy links to user_profiles table
+ * - Supports soft delete via deletedAt
+ *
+ * @example
+ * ```typescript
+ * const file: File = {
+ *   id: "file-123",
+ *   tenantId: "tenant-456",
+ *   name: "contract-2025.pdf",
+ *   originalName: "Contract Acme Corp 2025.pdf",
+ *   mimeType: "application/pdf",
+ *   size: 2458624,
+ *   storageProvider: "s3",
+ *   storagePath: "tenants/456/files/2025/11/contract-2025.pdf",
+ *   storageBucket: "my-app-files",
+ *   url: "https://cdn.example.com/files/file-123",
+ *   uploadedBy: "profile-789",
+ *   folderPath: "/contracts/2025",
+ *   createdAt: new Date(),
+ *   updatedAt: new Date(),
+ * };
+ * ```
+ */
+interface File extends Timestamps {
+    id: Uuid;
+    tenantId: Uuid;
+    /**
+     * File name (sanitized for storage)
+     */
+    name: string;
+    /**
+     * Original file name (as uploaded by user)
+     */
+    originalName: string;
+    /**
+     * MIME type (e.g., "application/pdf", "image/jpeg")
+     */
+    mimeType: MimeType | string;
+    /**
+     * File size in bytes
+     */
+    size: number;
+    /**
+     * Storage provider (s3, gcs, azure, local, etc.)
+     */
+    storageProvider: StorageProvider;
+    /**
+     * Path in the storage bucket
+     */
+    storagePath: string;
+    /**
+     * Storage bucket name (if applicable)
+     */
+    storageBucket?: string;
+    /**
+     * Public or signed URL to access the file
+     */
+    url: string;
+    /**
+     * User who uploaded the file (FK to user_profiles)
+     * Optional for system-generated files or anonymous uploads.
+     */
+    uploadedBy?: Uuid;
+    /**
+     * Folder path for organization (e.g., "/contracts/2025")
+     */
+    folderPath?: string;
+    /**
+     * Soft delete timestamp (null = not deleted)
+     */
+    deletedAt?: Date;
+    /**
+     * Document this file belongs to, when the file is a member of a document
+     * pack. NULL for files that aren't part of a document (e.g. freshly
+     * uploaded blobs not yet attached to a pack).
+     */
+    documentId?: Uuid | null;
+    /**
+     * Append-only position within the owning document pack (plain integer,
+     * `max(position) + 1`). Packs are NOT reorderable (spec §2).
+     */
+    position?: number | null;
+    /**
+     * OCR processing status for this file, when applicable.
+     */
+    ocrStatus?: FileOcrStatus | null;
+    /**
+     * Extracted OCR text, when processing has completed.
+     */
+    ocrText?: string | null;
+    /**
+     * OCR confidence score, when processing has completed.
+     */
+    ocrConfidence?: number | null;
+    /**
+     * Timestamp of the last OCR processing attempt.
+     */
+    processedAt?: Date | null;
+}
+/**
+ * Data required to create a new file record
+ */
+/**
+ * Data for creating a new file.
+ * Tenant ID is automatically set from execution context.
+ */
+interface CreateFile {
+    name: string;
+    originalName: string;
+    mimeType: MimeType | string;
+    size: number;
+    storageProvider: StorageProvider;
+    storagePath: string;
+    storageBucket?: string;
+    url: string;
+    uploadedBy?: Uuid;
+    folderPath?: string;
+    documentId?: Uuid | null;
+    position?: number | null;
+    ocrStatus?: FileOcrStatus | null;
+    ocrText?: string | null;
+    ocrConfidence?: number | null;
+    processedAt?: Date | null;
+}
+/**
+ * Data for updating an existing file record
+ */
+interface UpdateFile {
+    name?: string;
+    folderPath?: string;
+    documentId?: Uuid | null;
+    position?: number | null;
+    ocrStatus?: FileOcrStatus | null;
+    ocrText?: string | null;
+    ocrConfidence?: number | null;
+    processedAt?: Date | null;
+}
+
+/**
+ * Outcome of a compaction pass: a no-op (context already small enough), an LLM
+ * `summary`, or a degraded `truncation` (the summarizer failed/timed out/returned
+ * empty, so older messages were dropped and a notice injected). Canonical home —
+ * `runtime` re-exports this and `react` imports it; never duplicate the literals.
+ */
+type CompactionStrategy = "no-op" | "summary" | "truncation";
+type AgentRunStatus = "pending" | "running" | "completed" | "failed" | "cancelled" | "paused";
+type AgentSessionStatus = "active" | "idle" | "completed" | "failed" | "cancelled" | "waiting_human" | "waiting_agents" | "timeout" | "expired";
+/**
+ * Statuses a session never leaves. Lives beside the union it partitions so
+ * every consumer shares it — runtime orchestration decides whether to keep
+ * working, and the React SSE lifecycle decides whether to stay connected.
+ * Splitting them is how `timeout` and `expired` came to close a session on the
+ * server while the browser kept reconnecting to it.
+ */
+declare const SESSION_TERMINAL_STATUSES: readonly ["completed", "failed", "cancelled", "timeout", "expired"];
+type TerminalSessionStatus = (typeof SESSION_TERMINAL_STATUSES)[number];
+declare function isTerminalSessionStatus(status: AgentSessionStatus): status is TerminalSessionStatus;
+type AgentSessionMode = "interactive" | "autonomous";
+/** Whether a class of tool call is confirmed by a human or executed straight away. */
+type ApprovalMode = "ask" | "auto";
+/**
+ * An agent's declared stance per risk class. Code-owned and versioned: there is
+ * deliberately no policy table (see the `agent_execution_policies` guardrail).
+ */
+interface AgentApprovalPolicy {
+    mutation: ApprovalMode;
+    destructive: ApprovalMode;
+    outward: ApprovalMode;
+}
+declare const DEFAULT_APPROVAL_POLICY: AgentApprovalPolicy;
+/**
+ * The switch shown at the bottom-left of the composer. `auto` relaxes
+ * `mutation` only — deletions and outward sends keep asking.
+ */
+type SessionApprovalMode = "manual" | "auto";
+type AgentMissionPolicy = "off" | "observe" | "enforce";
+type AgentMissionStatus = "active" | "verifying" | "completed" | "needs_review" | "abandoned";
+declare const TODO_PLAN_STATUSES: readonly ["active", "completed", "promoted", "abandoned"];
+type AgentTodoPlanStatus = (typeof TODO_PLAN_STATUSES)[number];
+type TriggerEventType = "record.created" | "record.updated" | "record.deleted" | "form.submitted" | "agent.completed" | "webhook" | "schedule";
+type AgentTriggerType = Extract<TriggerEventType, "record.created" | "record.updated" | "record.deleted">;
+type ProviderName = "anthropic" | "openai" | "google" | "mistral";
+interface ModelDefinition {
+    provider: ProviderName;
+    model: string;
+    maxTokens?: number;
+    /**
+     * Total context window in tokens (e.g. 200000 for Claude Sonnet).
+     * Required by the compaction subsystem when this model is used as the
+     * summary model; optional otherwise.
+     */
+    contextWindow?: number;
+}
+interface RetryPolicy {
+    maxRetries: number;
+    backoffMs: number;
+    backoffMultiplier: number;
+}
+interface AgentExecutionConfig {
+    maxConcurrentRuns: number;
+    retryPolicy: RetryPolicy;
+    timeoutMs: number;
+    costLimitUsd?: number;
+}
+/**
+ * Shared base config used by AgentDefinition, inline runs, and AgentSession.
+ */
+interface AgentConfig {
+    systemPrompt: string;
+    model: ModelDefinition;
+    tools?: string[];
+    timeoutMs?: number;
+    costLimitUsd?: number | null;
+    canDelegate: boolean;
+    maxDepth: number;
+    maxTreeCostUsd?: number;
+    critic?: CriticConfig;
+    missionPolicy?: AgentMissionPolicy;
+}
+interface CriticConfig {
+    enabled: boolean;
+    model?: ModelDefinition;
+    systemPrompt?: string;
+    maxRetries?: number;
+}
+/**
+ * Standalone trigger definition (replaces embedded AgentTrigger[]).
+ * Triggers are now first-class entities with their own lifecycle.
+ */
+interface AgentTriggerDefinition {
+    id: string;
+    tenantId: string;
+    definitionId: string;
+    name?: string;
+    eventType: TriggerEventType;
+    objectId?: string;
+    watchedFields?: string[];
+    formDefinitionId?: string;
+    sourceAgentId?: string;
+    webhookPath?: string;
+    cronExpression?: string;
+    timezone?: string;
+    filter?: FilterState;
+    inputBuilder?: string;
+    debounceMs?: number;
+    enabled: boolean;
+    lastFiredAt?: Date;
+    createdAt: Date;
+    updatedAt: Date;
+}
+interface AgentSchedule {
+    cron: string;
+    timezone?: string;
+    enabled: boolean;
+    input?: Record<string, unknown>;
+    inputBuilder?: string;
+}
+/**
+ * Declarative trigger carried by an {@link AgentBlueprint}. The boot sync
+ * reconciles the agent's AgentTriggerDefinition rows to match, using `name`
+ * as the stable identity.
+ */
+/**
+ * System permission an actor must hold to see and use an agent. When
+ * declared, the agent listing and session-creation gates hide/refuse the
+ * agent for any actor lacking `action` on `resource` — checked via
+ * `PermissionService.canAccessSystemByActor`. Absent by default: the
+ * overwhelming majority of agents are visible to every actor.
+ */
+interface AgentRequiredPermission {
+    resource: SystemResource;
+    action: Action;
+}
+interface AgentTriggerBlueprint {
+    name: string;
+    eventType: TriggerEventType;
+    objectId?: string;
+    watchedFields?: string[];
+    formDefinitionId?: string;
+    sourceAgentId?: string;
+    webhookPath?: string;
+    cronExpression?: string;
+    timezone?: string;
+    filter?: FilterState;
+    inputBuilder?: string;
+    debounceMs?: number;
+    enabled: boolean;
+}
+/**
+ * Code-declared agent definition produced by the `agent()` builder.
+ * Contains everything an AgentDefinition needs except runtime-assigned
+ * fields (id, tenantId, createdBy, timestamps). `system: true` blueprints
+ * are seeded/reconciled at boot and immutable through the public API.
+ */
+interface AgentBlueprint {
+    name: string;
+    /**
+     * Display text shown wherever this agent's identity is rendered in the
+     * UI — `undefined` falls back to `name`. A separate concern from `name`
+     * on purpose: `name` is the stable identity the boot sync matches rows
+     * on (`system-agent-sync.service.ts`), so renaming the display text (or
+     * translating it) must never require touching that identity.
+     */
+    label?: string;
+    icon?: string;
+    description?: string;
+    systemPrompt: string;
+    model: ModelDefinition;
+    tools?: string[];
+    schedule?: AgentSchedule;
+    config: AgentExecutionConfig;
+    canDelegate?: boolean;
+    maxDepth?: number;
+    maxTreeCostUsd?: number;
+    system: boolean;
+    /** Code-declared agents are workspace-visible; private is runtime-only. */
+    visibility: ResourceVisibility;
+    triggers: AgentTriggerBlueprint[];
+    requiredPermission?: AgentRequiredPermission;
+    approval?: AgentApprovalPolicy;
+}
+interface AgentMessageAttachment {
+    id: string;
+    name: string;
+    mimeType: string;
+    size: number;
+}
+/**
+ * The text to show wherever an agent's identity is rendered — its `label`
+ * when declared, else its technical `name` verbatim (never capitalised or
+ * otherwise transformed here: every existing agent must keep rendering
+ * exactly as it does today until it explicitly declares a `label`).
+ */
+declare function agentDisplayName(agent: Pick<AgentBlueprint, "name" | "label">): string;
+interface AgentMissionArtifact {
+    path: string;
+    description: string;
+    mediaType?: string;
+}
+interface AgentMissionRubricCriterion {
+    id: string;
+    description: string;
+}
+interface AgentMissionRubric {
+    criteria: AgentMissionRubricCriterion[];
+    createdAt: string;
+}
+interface AgentMissionVerification {
+    cycle: number;
+    attempts: number;
+    maxAttempts: number;
+    lastVerdict?: "pass" | "fail";
+    lastFeedback?: string;
+    missingCriteria?: string[];
+    lastEvidenceHash?: string;
+    pendingEvidenceHash?: string;
+    lastAttemptAt?: string;
+    verifierCostUsd?: number;
+    verifierInputTokens?: number;
+    verifierOutputTokens?: number;
+}
+interface AgentMission {
+    id: string;
+    tenantId: string;
+    sessionId: string;
+    activationMessageId?: string;
+    status: AgentMissionStatus;
+    objective: string;
+    todos: AITodoItem[];
+    artifacts: AgentMissionArtifact[];
+    rubric?: AgentMissionRubric;
+    verification: AgentMissionVerification;
+    version: number;
+    createdBy?: string;
+    createdAt: Date;
+    updatedAt: Date;
+    completedAt?: Date;
+}
+/** UI-safe mission lifecycle snapshot returned by REST and realtime surfaces. */
+interface AgentMissionView {
+    id: string;
+    sessionId: string;
+    status: AgentMissionStatus;
+    objective: string;
+    todos: AITodoItem[];
+    artifacts: AgentMissionArtifact[];
+    verification: Pick<AgentMissionVerification, "cycle" | "attempts" | "maxAttempts" | "lastVerdict" | "lastFeedback" | "missingCriteria" | "lastAttemptAt">;
+    version: number;
+    createdAt: string;
+    updatedAt: string;
+    completedAt?: string;
+}
+interface AgentMissionPage {
+    items: AgentMissionView[];
+    nextCursor?: string;
+}
+/** A lightweight, pre-mission todo plan scoped to one agent session. */
+interface AgentTodoPlan {
+    id: string;
+    tenantId: string;
+    sessionId: string;
+    activationMessageId?: string;
+    status: AgentTodoPlanStatus;
+    todos: AITodoItem[];
+    version: number;
+    createdBy?: string;
+    createdAt: Date;
+    updatedAt: Date;
+    completedAt?: Date;
+    promotedMissionId?: string;
+}
+/** UI-safe todo plan lifecycle snapshot returned by REST and realtime surfaces. */
+interface AgentTodoPlanView {
+    id: string;
+    sessionId: string;
+    status: AgentTodoPlanStatus;
+    todos: AITodoItem[];
+    version: number;
+    createdAt: string;
+    updatedAt: string;
+    completedAt?: string;
+    promotedMissionId?: string;
+}
+interface AgentDefinition {
+    id: string;
+    tenantId: string;
+    name: string;
+    /** Display text shown wherever this agent's identity is rendered — see `AgentBlueprint.label`. `undefined` falls back to `name`. */
+    label?: string;
+    icon?: string;
+    description?: string;
+    systemPrompt: string;
+    model: ModelDefinition;
+    tools?: string[];
+    schedule?: AgentSchedule;
+    config: AgentExecutionConfig;
+    /** Code-declared (immutable via public API); reconciled by the boot sync. */
+    system: boolean;
+    visibility: ResourceVisibility;
+    ownedBy: string | null;
+    createdBy: string;
+    createdAt: Date;
+    updatedAt: Date;
+    deletedAt?: Date;
+    canDelegate?: boolean;
+    maxDepth?: number;
+    maxTreeCostUsd?: number;
+    critic?: CriticConfig;
+    missionPolicy?: AgentMissionPolicy;
+    autoDecide?: boolean;
+    fileIds?: string[];
+    attachments?: File[];
+    requiredPermission?: AgentRequiredPermission;
+}
+interface AgentRun {
+    id: string;
+    definitionId?: string;
+    parentRunId?: string;
+    depth: number;
+    inlineConfig?: AgentConfig;
+    tenantId: string;
+    createdBy?: string;
+    status: AgentRunStatus;
+    retryCount: number;
+    input: Record<string, unknown>;
+    output?: Record<string, unknown>;
+    error?: string;
+    tokenUsage?: {
+        input: number;
+        output: number;
+    };
+    costUsd?: number;
+    startedAt?: Date;
+    completedAt?: Date;
+    createdAt: Date;
+    sessionId?: string;
+    rootRunId?: string;
+    triggerId?: string;
+    /** Source domain-event id that launched this run; used for redelivery idempotency. */
+    sourceEventId?: string;
+    treeCostUsd?: number;
+    effectiveSystemPrompt?: string;
+    /** Monotonic fencing token, incremented on each lease acquisition. */
+    attemptId?: number;
+    /** Worker id currently holding the execution lease (null when free). */
+    leaseOwner?: string;
+    /** When the current lease expires; a run is re-acquirable once past this. */
+    leaseExpiresAt?: Date;
+}
+interface AgentSession {
+    id: string;
+    tenantId: string;
+    mode: AgentSessionMode;
+    status: AgentSessionStatus;
+    /**
+     * D4's SECOND approval level: the human's per-conversation switch. The first
+     * level is the agent's own code-declared {@link AgentApprovalPolicy}; both
+     * are read together by `requiresApproval`, and this one relaxes the
+     * `mutation` class ONLY.
+     *
+     * Required on read, not optional: the column is `NOT NULL DEFAULT 'auto'`,
+     * so every read path yields a concrete posture. Writes may omit it — see
+     * `AgentRepository.createSession`, whose input type drops it precisely
+     * because the default lives in the database.
+     */
+    approvalMode: SessionApprovalMode;
+    definitionId?: string;
+    inlineConfig?: AgentConfig;
+    parentSessionId?: string;
+    rootSessionId: string;
+    depth: number;
+    missionPrompt?: string;
+    treeCostUsd: number;
+    name?: string;
+    metadata?: Record<string, unknown>;
+    createdBy?: string;
+    createdAt: Date;
+    updatedAt: Date;
+    completedAt?: Date;
+    expiresAt?: Date;
+    archivedAt?: Date;
+    /** Per-actor read marker. Populated by list endpoints when the caller is known. */
+    lastReadAt?: Date;
+    /** Convenience flag: true when session has activity since `lastReadAt` (or never read). */
+    isUnread?: boolean;
+}
+type ToolPartState = "streaming" | "running" | "completed" | "error";
+/**
+ * Structured cause for a tool part that ended in `state: "error"` without the
+ * tool having run. Lets the UI render a localized explanation instead of the
+ * raw error string.
+ */
+type ToolPartErrorCode = "output_limit_reached" | "interrupted";
+/**
+ * Damage measured from a tool's input WITHOUT executing it — what a
+ * confirmation card states so the human decides on numbers rather than on a
+ * tool name (D3: "the confirmation quantifies the damage").
+ *
+ * Lives here, in the contracts package, because it is written to the message
+ * part (see `approvalImpact` below) and therefore crosses runtime, adapters
+ * and UI alike. The runtime's `ToolPreview`/`ToolRiskEntry` re-export it
+ * rather than redefining it.
+ */
+interface ToolImpact {
+    /** One human sentence, used as the confirmation title. */
+    label: string;
+    /**
+     * The authorization gate refused the call.
+     *
+     * A flag rather than a wording: the label is written server-side, where no
+     * recipient locale is in reach, so a refusal used to read "Suppression
+     * refusée" to every user in every language. The card renders its own copy
+     * from this.
+     */
+    denied?: boolean;
+    /**
+     * What a delete preview is about to remove, as data rather than as a
+     * sentence. The label is written server-side with no recipient locale in
+     * reach, so "Supprimer 12 records" reached every user in every language —
+     * and its thousands separator was pinned to `fr-FR` besides. The card
+     * composes its own headline from this.
+     */
+    deletion?: {
+        /** The record or document's own name; data, not copy. */
+        target?: string;
+        /** How many are going, when there is no single target to name. */
+        count?: number;
+        /** Days the deletion can still be undone, if it can. */
+        restorableDays?: number;
+    };
+    /** Named counts, e.g. `{ records: 1284, brokenLinks: 63 }`. */
+    counts?: Record<string, number>;
+    warnings?: string[];
+}
+/**
+ * Whether the agent's conclusion depends on the human it just sollicited (D7).
+ *
+ * - `required` (the default, fail-closed): the session PARKS on the request and
+ *   RESUMES the parked turn when the answer lands. Forgetting to declare
+ *   anything therefore produces a visible wait, never a human answer thrown
+ *   into a void.
+ * - `optional`: the session TERMINATES normally with the request still in
+ *   flight, and the answer REOPENS it through a new turn. Without this, an
+ *   incidental question would immobilise the conversation for the full 24h
+ *   expiry horizon — sandbox anchored to the tree, lease held, and a finished
+ *   conversation displayed as "in progress".
+ *
+ * Orthogonal to who does the work: this says only WHETHER we wait.
+ *
+ * Lives here, in the contracts package, because it is written to the message
+ * part (see `humanRequestNeed` below) and therefore crosses runtime, adapters
+ * and UI alike.
+ */
+type HumanRequestNeed = "required" | "optional";
+type AgentMessagePart = {
+    type: "text";
+    text: string;
+} | {
+    type: "reasoning";
+    text: string;
+} | {
+    type: "error";
+    error: string;
+    errorClass?: string;
+} | {
+    type: "tool";
+    toolCallId: string;
+    name: string;
+    args: Record<string, unknown>;
+    result?: unknown;
+    error?: string;
+    errorCode?: ToolPartErrorCode;
+    state: ToolPartState;
+    durationMs?: number;
+    /**
+     * Set when this call was suspended by the approval gate (a risky tool
+     * awaiting a human decision — see `toolApproval` in the AI SDK config).
+     * The part legitimately stays in its current state (`running`) with no
+     * result/error while the human decides; presence of this id is what
+     * distinguishes "waiting on a human" from "crashed mid-call" on resume,
+     * for ANY tool name — unlike the HITL exemption, which is keyed on a
+     * fixed set of tool names (`ask_questions`).
+     */
+    approvalId?: string;
+    /**
+     * What this suspended call would do, measured ONCE at suspension time
+     * from the tool's declared `preview` (D13). Persisted next to
+     * `approvalId` instead of being recomputed per reader: the same card is
+     * rendered by three hosts (composer, notification queue, record
+     * banner), and a queue of ten pending requests would otherwise fire ten
+     * previews per host. The UI therefore shows it dated ("12 records · 4
+     * min ago"), bounded by the 24h expiry.
+     *
+     * Absent when the tool declares no `preview` (a `mutation`-class tool
+     * cannot have one, by construction of `ToolRiskEntry`) or when the
+     * preview threw — a broken preview must never swallow the suspension.
+     */
+    approvalImpact?: ToolImpact;
+    /**
+     * The human's decision on `approvalId`: `true` approved, `false` refused.
+     * Absent while the decision is still pending. The approver's identity is
+     * carried by the audit trail, not this field.
+     */
+    approved?: boolean;
+    /**
+     * The human's optional rationale for `approved` (Finding 3, final
+     * review): why they decided as they did. Purely informational — it
+     * never changes what executes, only what the agent (and any audit
+     * reader) is told about the decision.
+     */
+    approvalReason?: string;
+    /**
+     * Whether this call's human request gates the agent's conclusion (D7) —
+     * set on ANY part that is awaiting a human, both an `ask_questions` call
+     * (declared by the agent through the tool's own `answerNeed` input) and
+     * an approval-gated call (always `required`: the tool cannot run at all
+     * until someone decides).
+     *
+     * Absent means `required` too — that is the fail-closed reading every
+     * consumer must apply (`resolveHumanRequestNeed`), so a pre-migration row
+     * or a shape this codebase failed to stamp can only ever produce a
+     * visible wait, never a silently dropped human answer.
+     */
+    humanRequestNeed?: HumanRequestNeed;
+    /**
+     * Whether the session's `auto` mode would have let THIS call through —
+     * i.e. whether offering "always allow this here" on its card would be
+     * honest. Computed server-side at suspension by re-evaluating the one
+     * owner of the decision (`requiresApproval`) with `sessionMode: "auto"`,
+     * so it can never drift from the policy: it IS the policy, asked a
+     * different question.
+     *
+     * It exists because the card cannot infer it. The tempting shortcut —
+     * "no measured impact means `mutation`, since only `destructive` and
+     * `outward` carry a `preview`" — is false: a preview that threw or timed
+     * out also yields no impact, so a deletion would masquerade as a
+     * mutation and the card would promise an ease the mode does not grant.
+     *
+     * Absent means "do not offer it", which is the fail-closed reading a
+     * pre-migration row must produce.
+     */
+    approvalRelaxableByAuto?: boolean;
+} | {
+    type: "file";
+    fileId: string;
+    name: string;
+    mimeType: string;
+} | {
+    type: "compaction";
+    state: "in-progress";
+    reason: "preflight_threshold" | "overflow_recovery";
+    estimatedTokens?: number;
+    reportedTokens?: number;
+} | {
+    type: "compaction";
+    state: "completed";
+    tokensBefore: number;
+    tokensAfter: number;
+    tokensSaved: number;
+    strategy: CompactionStrategy;
+    durationMs: number;
+    /**
+     * Raw summary text produced by the summarizer LLM. Persisted so that
+     * follow-up turns can reuse it instead of re-running the summarizer.
+     */
+    summary?: string;
+} | {
+    type: "compaction";
+    state: "failed";
+    /** Human-readable reason from the CompactionImpossibleError. */
+    reason: string;
+    durationMs?: number;
+};
+/**
+ * Persisted message in an agent session.
+ * Unified type for both interactive and autonomous sessions.
+ */
+interface AgentSessionMessage {
+    id: string;
+    sessionId: string;
+    tenantId?: string;
+    runId?: string;
+    role: "user" | "assistant" | "system" | "tool";
+    parts: AgentMessagePart[];
+    attachments?: AgentMessageAttachment[];
+    mentions?: MentionReference[];
+    model?: ModelDefinition;
+    tokenUsage?: {
+        input: number;
+        output: number;
+    };
+    metadata?: Record<string, unknown>;
+    createdAt: Date;
+}
+interface AgentToolCall {
+    id: string;
+    name: string;
+    arguments: Record<string, unknown>;
+    result?: unknown;
+    error?: string;
+    durationMs?: number;
+    /** Set by StreamEventAccumulator.reconcile() when the tool call was cut off before completing. */
+    errorCode?: ToolPartErrorCode;
+}
+interface RecordAgentEvent {
+    type: AgentTriggerType;
+    objectId: string;
+    recordId: string;
+    tenantId: string;
+    data?: Record<string, unknown>;
+}
+interface FormSubmittedAgentEvent {
+    type: "form.submitted";
+    tenantId: string;
+    formId: string;
+    formName: string;
+    submissionId: string;
+    createdBy?: string;
+    createdRecordIds: Record<string, string>;
+    data: {
+        formId: string;
+        formName: string;
+        submissionId: string;
+        createdBy?: string;
+        createdRecordIds: Record<string, string>;
+        slotValues: Record<string, Record<string, unknown>>;
+        stepValues: Record<string, Record<string, unknown>>;
+    };
+}
+type AgentEvent = RecordAgentEvent | FormSubmittedAgentEvent;
+interface AgentDashboard {
+    activeRuns: number;
+    pendingRuns: number;
+    failedToday: number;
+    completedToday: number;
+    totalCostToday: number;
+    totalCostWeek: number;
+}
+/**
+ * Message role in a conversation
+ */
+type AIMessageRole = "user" | "assistant";
+/**
+ * An AI model available for selection by the user.
+ * Configured on the backend and exposed via GET /agent/models.
+ */
+interface AIAvailableModel {
+    /** Model identifier exposed to the UI (e.g. "claude-sonnet-4-6") */
+    id: string;
+    /**
+     * Provider model ID sent to the underlying SDK. Defaults to `id` when omitted.
+     * Use this to register multiple registry entries (different `contextWindow`,
+     * `label`, etc.) that route to the same upstream model — e.g. a test entry
+     * with a reduced context window for QA of the compaction system.
+     */
+    apiModelId?: string;
+    /** Provider name (e.g. "anthropic", "google") */
+    provider: string;
+    /** Display label (e.g. "Claude 4.6 Sonnet") */
+    label: string;
+    /** Whether this is the default model */
+    isDefault?: boolean;
+    /**
+     * Total context window in tokens. Optional — resolved from the vendored
+     * models.dev snapshot when omitted. Set explicitly only for a deliberate cap
+     * (e.g. a QA reduced-window entry).
+     */
+    contextWindow?: number;
+    /**
+     * Maximum output tokens. Optional — resolved from the models.dev snapshot when
+     * omitted. Set explicitly only for a deliberate cap.
+     */
+    maxOutputTokens?: number;
+    /**
+     * Set true for a model newer than the models.dev snapshot. When true,
+     * `contextWindow` and `maxOutputTokens` MUST be provided explicitly. Token
+     * cost stays unknown (never developer-specified) until the snapshot lists it.
+     */
+    unverified?: boolean;
+    /** If true, this model is used for generating compaction summaries */
+    isCompactionModel?: boolean;
+    /** If true, this model is used for fast utility generations (regex, formula, …) */
+    isUtilityModel?: boolean;
+}
+/**
+ * Tool call status during execution
+ */
+type AIToolCallStatus = "pending" | "running" | "streaming" | "success" | "error";
+/**
+ * Tool call information for chat UI
+ */
+interface AIToolCall {
+    /** Unique tool call ID */
+    id: string;
+    /** Tool name */
+    name: string;
+    /** Tool arguments */
+    args?: Record<string, unknown>;
+    /** Tool result (when complete) */
+    result?: unknown;
+    /** Error message if failed */
+    error?: string;
+    /** Execution status */
+    status: AIToolCallStatus;
+}
+/**
+ * Part type for message content
+ */
+type AIChatMessagePartType = "text" | "attachment" | "tool" | "thinking" | "reasoning" | "todo" | "question" | "error" | "approval" | "record" | "search-results" | "compaction" | (string & {});
+/**
+ * Data for text part
+ */
+interface TextPartData {
+    text: string;
+    isStreaming?: boolean;
+}
+/**
+ * Data for tool part (same as AIToolCall)
+ */
+interface ToolPartData {
+    id: string;
+    name: string;
+    args?: Record<string, unknown>;
+    result?: unknown;
+    error?: string;
+    errorCode?: ToolPartErrorCode;
+    status: AIToolCallStatus;
+    /** Raw JSON string accumulating during tool-input streaming (cleared on tool_input_end) */
+    partialInput?: string;
+    /**
+     * Set when this call is suspended pending a human approval decision — mirrors
+     * `AgentMessagePart`'s `"tool"` variant so a reloaded conversation still shows
+     * the call as awaiting a human rather than as a generic "running" state.
+     */
+    approvalId?: string;
+    /**
+     * What the suspended call would do, as measured ONCE at suspension time and
+     * persisted on the part (D13) — never recomputed by the renderer. Because
+     * the number is a snapshot of that moment and the request lives up to 24h,
+     * the card must show it DATED ("3 records · il y a 4 min") rather than as a
+     * live count. Absent when the tool declared no preview, or when the preview
+     * threw: a degraded card, never a lost one.
+     */
+    approvalImpact?: ToolImpact;
+    /**
+     * The human's decision, once recorded: `true` approved, `false` refused,
+     * `undefined` still pending. It has to reach the renderer, not just the
+     * request: between the decision and the end of the re-execution the part
+     * legitimately stays `running` WITH its `approvalId`, so a card keyed on
+     * `approvalId` alone would come back offering two live buttons on a request
+     * that is already settled.
+     */
+    approved?: boolean;
+    /**
+     * Whether the session's `auto` mode would have let this call through, so the
+     * card knows if "always allow this here" is an honest offer. Mirrors
+     * `AgentMessagePart`'s field of the same name — see it for why the card
+     * cannot derive this itself. Absent means do not offer it.
+     */
+    approvalRelaxableByAuto?: boolean;
+}
+/**
+ * Data for thinking part
+ */
+interface ThinkingPartData {
+    isStreaming: boolean;
+    startTime?: number;
+}
+/**
+ * Data for reasoning part (Extended Thinking content)
+ */
+interface ReasoningPartData {
+    /** Reasoning content (accumulated during streaming) */
+    content: string;
+    /** Whether reasoning is still streaming */
+    isStreaming: boolean;
+    /** Start timestamp for elapsed time display */
+    startTime?: number;
+}
+/**
+ * A part of a chat message.
+ * Parts are ordered chronologically as they arrive from the stream.
+ */
+interface AIChatMessagePart {
+    /** Part type */
+    type: AIChatMessagePartType;
+    /** Unique part ID */
+    id: string;
+    /** Part-specific data */
+    data: unknown;
+}
+/**
+ * Terminal status of a dispatched subagent, mirrored onto the parent-visible
+ * notification. `completed` reads as success; everything else reads as failure.
+ */
+type AISubagentStatus = "completed" | "failed" | "cancelled" | "timeout" | "expired";
+/**
+ * Narrow, UI-ready projection of an `agent-notification` message. Derived by the
+ * react mapper from the raw `AgentSessionMessage.metadata` so the UI never has to
+ * touch untrusted wrapper text: the title comes from {@link childName}/{@link status}
+ * and {@link body} is the child's report already unwrapped from its `<subagent_result>`
+ * envelope.
+ */
+interface AIChatNotification {
+    childSessionId: string;
+    childName: string;
+    status: AISubagentStatus;
+    /** Child's report, unwrapped from the `<subagent_result>` envelope; rendered as markdown. */
+    body: string;
+}
+/**
+ * Chat message for runtime/streaming.
+ *
+ * All content is represented as ordered parts (text, tools, thinking, etc.)
+ * Parts are in chronological order as they arrive from the stream.
+ *
+ * Used in:
+ * - useAgentChat hook
+ * - AI chat UI components
+ * - Stream processing
+ */
+interface AIChatMessage {
+    /** Unique message ID */
+    id: string;
+    /** Message role */
+    role: AIMessageRole;
+    /** Ordered message parts (text, tools, thinking, etc.) */
+    parts: AIChatMessagePart[];
+    /** Whether the message is still streaming */
+    isStreaming?: boolean;
+    /** Message timestamp */
+    timestamp?: Date;
+    /** Error message if the message failed */
+    error?: string;
+    /**
+     * Present only for subagent-completion notifications. When set, the UI renders
+     * a compact collapsible callout in the agent flow instead of a user bubble, and
+     * ignores {@link parts} (which still hold the raw wrapper text).
+     */
+    notification?: AIChatNotification;
+    /**
+     * Tokens reported by the provider after this message completed. The `input`
+     * value reflects the size of the conversation Anthropic actually saw on
+     * that turn — used by the chat composer to render a context-window
+     * progress ring.
+     */
+    tokenUsage?: {
+        input: number;
+        output: number;
+    };
+}
+/**
+ * Question types supported by the agent
+ */
+type AIQuestionType = "text" | "choice" | "confirm" | "multiselect";
+/**
+ * Option for choice/multiselect questions
+ */
+interface AIQuestionOption {
+    value: string;
+    label: string;
+    description?: string;
+}
+/**
+ * Question from the agent to the user
+ */
+interface AIQuestion {
+    /** Unique question ID */
+    id: string;
+    /** Question type */
+    type: AIQuestionType;
+    /** Question text */
+    question: string;
+    /** Options for choice/multiselect */
+    options?: AIQuestionOption[];
+    /** Placeholder for text input */
+    placeholder?: string;
+    /** Whether answer is required */
+    required?: boolean;
+    /** Min selections for multiselect */
+    minSelections?: number;
+    /** Max selections for multiselect */
+    maxSelections?: number;
+}
+/**
+ * Answer format for questions
+ */
+type AIQuestionAnswer = {
+    type: "text";
+    value: string;
+} | {
+    type: "choice";
+    value: string;
+} | {
+    type: "confirm";
+    value: boolean;
+} | {
+    type: "multiselect";
+    value: string[];
+};
+/**
+ * Option for batch questions
+ */
+interface AIBatchQuestionOption {
+    /** Value returned when selected */
+    value: string;
+    /** Display label */
+    label: string;
+    /**
+     * What choosing this option means, or what it costs. Rendered under the
+     * label, in the quiet weight: a batch of bare labels asks the human to
+     * infer the trade-off the agent already knows.
+     */
+    description?: string;
+}
+/**
+ * Kind of field a batch question is answered with.
+ *
+ * `record` (constraining the answer to a real `recordId`) is deliberately
+ * absent: it needs a record selector, which is a feature of its own rather
+ * than a field variant.
+ */
+type AIBatchQuestionType = "choice" | "text" | "boolean";
+/**
+ * Question in a batch (for ask_questions tool)
+ */
+interface AIBatchQuestion {
+    /** Unique question ID */
+    id: string;
+    /** Question text to display */
+    question: string;
+    /**
+     * Kind of field to answer with. Optional for backwards compatibility: when
+     * absent it is derived from the shape — `options` present means `choice`,
+     * otherwise `text`. Only `boolean` cannot be derived, so it must be declared.
+     */
+    type?: AIBatchQuestionType;
+    /** Predefined options (if provided, displayed as buttons) */
+    options?: AIBatchQuestionOption[];
+    /**
+     * Several options may be chosen at once, and the answer comes back as an
+     * array. Decided by the agent per question, because only it knows whether
+     * the choices are mutually exclusive; a human forced to pick one of three
+     * non-exclusive options answers a question nobody asked.
+     */
+    multiSelect?: boolean;
+    /** Allow custom text input in addition to options */
+    allowCustomAnswer?: boolean;
+    /** Placeholder for custom input field */
+    placeholder?: string;
+}
+/**
+ * A single answer, in the type the question asked for. A `boolean` question
+ * answered with the string `"true"` would leave the model re-parsing display
+ * text — the same class of mistake as returning an option's label instead of
+ * its value. A `multiSelect` question answers with the array for the same
+ * reason: joining it into `"a, b"` would hand the model a string to split back
+ * apart, and one whose separator can appear inside a value.
+ */
+type AIBatchAnswerValue = string | boolean | string[];
+/**
+ * Answer returned by the AgentQuestions widget
+ */
+interface AIBatchQuestionAnswer {
+    /** True if user skipped all questions */
+    skipped: boolean;
+    /** Map of question ID to the answer given, in the question's own type */
+    answers: Record<string, AIBatchAnswerValue>;
+}
+/**
+ * Todo item status
+ */
+declare const TODO_STATUSES: readonly ["pending", "in_progress", "completed", "blocked"];
+type AITodoStatus = (typeof TODO_STATUSES)[number];
+/**
+ * Todo item in a task list
+ */
+interface AITodoItem {
+    id: string;
+    description: string;
+    status: AITodoStatus;
+    result?: string;
+    updatedAt?: number;
+}
+/**
+ * Persisted bounds on a todo, beside the type they constrain.
+ *
+ * Both sides of the wire enforce them: the runtime zod schema when it writes,
+ * and the React projection parser when it reads an untrusted payload back.
+ * React cannot import the runtime, which is why these numbers used to be
+ * copied there under a "keep aligned with the canonical persisted schema"
+ * comment — a synchronisation the compiler could not check.
+ */
+declare const MAX_TODOS = 50;
+declare const MAX_TODO_ID_CHARS = 80;
+declare const MAX_TODO_DESCRIPTION_CHARS = 500;
+declare const MAX_TODO_RESULT_CHARS = 2000;
+/**
+ * Todo list managed by the agent
+ */
+interface AITodoList {
+    items: AITodoItem[];
+    progress: number;
+    isComplete: boolean;
+}
+/**
+ * AI Usage Metrics record
+ */
+interface AIUsageMetrics {
+    id: string;
+    tenantId: string;
+    date: Date;
+    requestCount: number;
+    totalTokens: number;
+    totalCost: number;
+    providerBreakdown: Record<string, AIProviderMetrics>;
+    toolUsage: Record<string, number>;
+}
+/**
+ * Provider-specific metrics
+ */
+interface AIProviderMetrics {
+    requests: number;
+    tokens: number;
+    cost: number;
+}
+/**
+ * Memory type for categorization
+ *
+ * - `soul`: Tenant identity and persona (admin-managed)
+ * - `user`: Per-user facts and preferences
+ * - `daily`: Auto-generated daily summaries
+ * - `session`: Auto-generated conversation summaries
+ */
+type AIMemoryType = "soul" | "user" | "daily" | "session";
+/**
+ * Advanced memory entry for OpenClaw-style memory system
+ */
+interface AIMemoryEntry {
+    id: string;
+    tenantId: string;
+    userId: string | null;
+    conversationId: string | null;
+    type: AIMemoryType;
+    content: string;
+    embedding: number[] | null;
+    importance: number;
+    source: string;
+    createdAt: Date;
+    updatedAt: Date;
+    expiresAt: Date | null;
+}
+/**
+ * Compaction summary for conversation history compression
+ */
+interface AICompactionSummary {
+    id: string;
+    tenantId: string;
+    userId: string;
+    conversationId: string;
+    summary: string;
+    originalMessageCount: number;
+    tokenCountBefore: number;
+    tokenCountAfter: number;
+    compactedAt: Date;
+}
+
+interface AddAttributeInput {
+    name: string;
+    label: string;
+    type: AttributeType;
+    required?: boolean;
+    unique?: boolean;
+    description?: string;
+    placeholder?: string;
+    icon?: IconName;
+    defaultValue?: unknown;
+    metadata?: Record<string, unknown>;
+    [key: string]: unknown;
+}
+interface CreateCustomObjectInput {
+    name: string;
+    label: string;
+    pluralLabel?: string;
+    labelExpression: string;
+    embeddingExpression?: string;
+    description?: string;
+    icon?: IconName;
+    attributes?: (Attribute | {
+        build: () => Attribute;
+    })[];
+    metadata?: Record<string, unknown>;
+}
+interface UpdateObjectInput {
+    label?: string;
+    pluralLabel?: string;
+    description?: string;
+    icon?: IconName;
+    labelExpression?: string;
+    embeddingExpression?: string;
+    metadata?: Record<string, unknown>;
+}
+interface CreateViewInput {
+    objectName: string;
+    type: ViewType;
+    name: string;
+    label: string;
+    description?: string;
+    icon?: IconName;
+    config: ViewConfig;
+    default?: boolean;
+    metadata?: Record<string, unknown>;
+}
+interface UpdateViewInput {
+    label?: string;
+    description?: string;
+    icon?: IconName;
+    config?: ViewConfig;
+    default?: boolean;
+    metadata?: Record<string, unknown>;
+}
+interface RelationOption {
+    id: string;
+    objectId: string;
+    objectName: string;
+    objectLabel: string;
+    objectIcon?: string;
+    label: string;
+}
+interface RelationOptionsResponse {
+    options: RelationOption[];
+    hasMore: boolean;
+    total: number;
+    nextOffset?: number;
+}
+interface StreamEventMessagePersisted {
+    type: "message_persisted";
+    message: AgentSessionMessage;
+}
+/**
+ * An already-persisted message had its parts updated out-of-band (e.g. a
+ * pending HITL tool part closed when the user replied). Clients replace the
+ * stored message in place without touching streaming state.
+ */
+interface StreamEventMessageUpdated {
+    type: "message_updated";
+    message: AgentSessionMessage;
+}
+/** A committed, UI-safe mission lifecycle snapshot. */
+interface StreamEventMissionUpdate {
+    type: "mission_update";
+    mission: AgentMissionView;
+}
+/** A committed, UI-safe lightweight todo plan lifecycle snapshot. */
+interface StreamEventTodoPlanUpdate {
+    type: "todo_plan_update";
+    plan: AgentTodoPlanView;
+}
+interface StreamEventCompactionStart {
+    type: "compaction_start";
+    reason: "preflight_threshold" | "overflow_recovery";
+    estimatedTokens?: number;
+    reportedTokens?: number;
+}
+interface StreamEventCompactionEnd {
+    type: "compaction_end";
+    tokensBefore: number;
+    tokensAfter: number;
+    tokensSaved: number;
+    strategy: CompactionStrategy;
+    durationMs: number;
+    summary?: string;
+}
+interface StreamEventCompactionFailed {
+    type: "compaction_failed";
+    reason: string;
+}
+/**
+ * Emitted once per agent turn, just before `complete`, carrying the exact
+ * provider token usage enriched with context-window utilization and cost.
+ * All fields are computed server-side — consumers display without recalculating.
+ */
+interface StreamEventUsage {
+    type: "usage";
+    inputTokens: number;
+    outputTokens: number;
+    totalTokens: number;
+    cacheReadTokens?: number;
+    cacheCreationTokens?: number;
+    /** Context window size of the model (in tokens). */
+    contextWindow: number;
+    /** totalTokens / contextWindow, clamped to [0, 1]. Computed server-side. */
+    utilization: number;
+    /** Estimated cost in USD. Undefined when pricing is unknown — never faked. */
+    costUsd?: number;
+}
+
+declare const statusGroupSchema: z.ZodEnum<{
+    idle: "idle";
+    in_progress: "in_progress";
+    finished: "finished";
+}>;
+declare const selectOptionWriteSchema: z.ZodObject<{
+    value: z.ZodString;
+    label: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+    inverse: z.ZodOptional<z.ZodString>;
+    archived: z.ZodOptional<z.ZodBoolean>;
+    color: z.ZodEnum<{
+        gray: "gray";
+        slate: "slate";
+        blue: "blue";
+        sky: "sky";
+        indigo: "indigo";
+        green: "green";
+        emerald: "emerald";
+        teal: "teal";
+        red: "red";
+        rose: "rose";
+        yellow: "yellow";
+        amber: "amber";
+        orange: "orange";
+        purple: "purple";
+        violet: "violet";
+        fuchsia: "fuchsia";
+        pink: "pink";
+        cyan: "cyan";
+        lime: "lime";
+    }>;
+}, z.core.$strict>;
+declare const multiselectOptionWriteSchema: z.ZodObject<{
+    value: z.ZodString;
+    label: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+    inverse: z.ZodOptional<z.ZodString>;
+    archived: z.ZodOptional<z.ZodBoolean>;
+    color: z.ZodEnum<{
+        gray: "gray";
+        slate: "slate";
+        blue: "blue";
+        sky: "sky";
+        indigo: "indigo";
+        green: "green";
+        emerald: "emerald";
+        teal: "teal";
+        red: "red";
+        rose: "rose";
+        yellow: "yellow";
+        amber: "amber";
+        orange: "orange";
+        purple: "purple";
+        violet: "violet";
+        fuchsia: "fuchsia";
+        pink: "pink";
+        cyan: "cyan";
+        lime: "lime";
+    }>;
+}, z.core.$strict>;
+declare const statusOptionWriteSchema: z.ZodObject<{
+    value: z.ZodString;
+    label: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+    inverse: z.ZodOptional<z.ZodString>;
+    archived: z.ZodOptional<z.ZodBoolean>;
+    color: z.ZodEnum<{
+        gray: "gray";
+        slate: "slate";
+        blue: "blue";
+        sky: "sky";
+        indigo: "indigo";
+        green: "green";
+        emerald: "emerald";
+        teal: "teal";
+        red: "red";
+        rose: "rose";
+        yellow: "yellow";
+        amber: "amber";
+        orange: "orange";
+        purple: "purple";
+        violet: "violet";
+        fuchsia: "fuchsia";
+        pink: "pink";
+        cyan: "cyan";
+        lime: "lime";
+    }>;
+    group: z.ZodEnum<{
+        idle: "idle";
+        in_progress: "in_progress";
+        finished: "finished";
+    }>;
+}, z.core.$strict>;
+/**
+ * Map of attribute type to config schema
+ */
+declare const attributeConfigSchemas: Record<AttributeType, z.ZodObject<z.ZodRawShape>>;
+/**
+ * Get the config schema for a specific attribute type
+ */
+declare function getAttributeConfigSchema(type: AttributeType): z.ZodObject<z.ZodRawShape>;
+/**
+ * Validate and strip unknown properties from attribute config
+ * This ensures only allowed properties are stored in the database
+ */
+declare function parseAttributeConfig(type: AttributeType, config: Record<string, unknown>): Record<string, unknown>;
+/**
+ * Strict parser for newly created attribute definitions.
+ *
+ * Top-level config remains strip-compatible with the historical config
+ * contract, while newly written icons and select-like option objects are
+ * validated strictly.
+ */
+declare function parseAttributeConfigForCreate(type: AttributeType, input: unknown): Record<string, unknown>;
+/**
+ * Patch-aware parser for persisted attributes.
+ *
+ * An explicit options patch owns and strictly validates the complete new
+ * list. Omission means the stored legacy list is preserved without
+ * reconstruction, including options that predate required colours/groups.
+ */
+declare function parseAttributeConfigForUpdate(stored: Attribute, patch: Partial<AddAttributeInput>): Record<string, unknown>;
+
+export { type AIQuestionOption as $, type Action as A, type AIBatchQuestion as B, type ConfigOverrides as C, type DetailViewConfig as D, type AIBatchQuestionAnswer as E, type FilterState as F, type Group as G, type AIBatchQuestionOption as H, type AIBatchQuestionType as I, type AIChatMessage as J, type AIChatMessagePart as K, type ListViewConfig as L, type ModelDefinition as M, type AIChatMessagePartType as N, type AIChatNotification as O, type PermissionScope as P, type AICompactionSummary as Q, type RelationGroup as R, type SortRule as S, type TriggerEventType as T, type AIMemoryEntry as U, type ViewType as V, type AIMemoryType as W, type AIMessageRole as X, type AIProviderMetrics as Y, type AIQuestion as Z, type AIQuestionAnswer as _, type ViewConfig as a, type EffectivePermissions as a$, type AIQuestionType as a0, type AISubagentStatus as a1, type AITodoItem as a2, type AITodoList as a3, type AITodoStatus as a4, type AIToolCall as a5, type AIToolCallStatus as a6, type AIUsageMetrics as a7, ALL_ACTIONS as a8, type AccessLevel as a9, type AgentTodoPlanStatus as aA, type AgentTodoPlanView as aB, type AgentToolCall as aC, type AgentTriggerDefinition as aD, type AgentTriggerType as aE, type ApprovalMode as aF, type AssignRoleInput as aG, type CompactionStrategy as aH, type CreateCustomObjectInput as aI, type CreateDocument as aJ, type CreateDocumentLink as aK, type CreateFile as aL, type CreatePermissionInput as aM, type CreateRoleInput as aN, type CreateViewInput as aO, type CriticConfig as aP, type CurrencyFilterValue as aQ, type CustomTab as aR, DEFAULT_APPROVAL_POLICY as aS, type Document as aT, type DocumentFile as aU, type DocumentKind as aV, type DocumentListOptions as aW, type DocumentWithFiles as aX, type DocumentWithSubCount as aY, type DocumentsTab as aZ, type EdgeQuantifier as a_, type ActivityTab as aa, type AddAttributeInput as ab, type AdvancedFilterState as ac, type AgentConfig as ad, type AgentDashboard as ae, type AgentDefinition as af, type AgentEvent as ag, type AgentMessageAttachment as ah, type AgentMessagePart as ai, type AgentMission as aj, type AgentMissionArtifact as ak, type AgentMissionPage as al, type AgentMissionPolicy as am, type AgentMissionRubric as an, type AgentMissionRubricCriterion as ao, type AgentMissionStatus as ap, type AgentMissionVerification as aq, type AgentMissionView as ar, type AgentRequiredPermission as as, type AgentRun as at, type AgentRunStatus as au, type AgentSession as av, type AgentSessionMessage as aw, type AgentSessionMode as ax, type AgentSessionStatus as ay, type AgentTodoPlan as az, type FilterOperator as b, type UpdateObjectInput as b$, type EmailsTab as b0, type ExtendedFilterRule as b1, type File as b2, type FileOcrStatus as b3, type FilterCombinator as b4, type FilterGroup as b5, type FormDensity as b6, type FormSubmittedAgentEvent as b7, type FormTab as b8, type FormsTab as b9, type Role as bA, SESSION_TERMINAL_STATUSES as bB, type SessionApprovalMode as bC, type SortDirection as bD, type StorageProvider as bE, type StreamEventCompactionEnd as bF, type StreamEventCompactionFailed as bG, type StreamEventCompactionStart as bH, type StreamEventMessagePersisted as bI, type StreamEventMessageUpdated as bJ, type StreamEventMissionUpdate as bK, type StreamEventTodoPlanUpdate as bL, type StreamEventUsage as bM, type SystemPermissions as bN, TODO_PLAN_STATUSES as bO, TODO_STATUSES as bP, type TabType as bQ, type TableSource as bR, type TerminalSessionStatus as bS, type TextPartData as bT, type ThinkingPartData as bU, type ToolImpact as bV, type ToolPartData as bW, type ToolPartErrorCode as bX, type ToolPartState as bY, type UpdateDocument as bZ, type UpdateFile as b_, type HumanRequestNeed as ba, type InverseSource as bb, type ListViewLayout as bc, MAX_TODOS as bd, MAX_TODO_DESCRIPTION_CHARS as be, MAX_TODO_ID_CHARS as bf, MAX_TODO_RESULT_CHARS as bg, type MentionEntityType as bh, type MentionReference as bi, type MentionedContext as bj, type MentionedEntityContext as bk, NO_VALUE_OPERATORS as bl, type NoValueOperator as bm, OPERATORS_BY_TYPE as bn, type ObjectPermissions as bo, type Permission as bp, type PhoneFilterValue as bq, type QueryState as br, type ReasoningPartData as bs, type RecordAgentEvent as bt, type RecordDocuments as bu, type RelationOption as bv, type RelationOptionsResponse as bw, type RelationSource as bx, type RetryPolicy as by, type RichtextTab as bz, type SystemResource as c, type UpdateRoleInput as c0, type UpdateViewInput as c1, type UserRoleAssignment as c2, type ViewOverlay as c3, accessLevelToActions as c4, actionsToAccessLevel as c5, agentDisplayName as c6, getRollupFilterOperators as c7, isDetailView as c8, isFieldGroup as c9, isListView as ca, isNoValueOperator as cb, isRelationGroup as cc, isTerminalSessionStatus as cd, multiselectOptionWriteSchema as ce, parseAttributeConfig as cf, parseAttributeConfigForCreate as cg, parseAttributeConfigForUpdate as ch, selectOptionWriteSchema as ci, statusGroupSchema as cj, statusOptionWriteSchema as ck, attributeConfigSchemas as cl, getAttributeConfigSchema as cm, type ProviderName as d, type AgentSchedule as e, type AgentExecutionConfig as f, type AgentApprovalPolicy as g, type AgentTriggerBlueprint as h, type AgentBlueprint as i, type DetailViewDefinition as j, type SidePanelConfig as k, type Field as l, type AttributeGroupField as m, type FieldGroup as n, type TableTab as o, type CreateMode as p, type Tab as q, type ListViewDefinition as r, type ViewDefinition as s, type ListViewTab as t, type FilterValue as u, type FilterRule as v, type DynamicValue as w, type RelativeDateValue as x, type AIAvailableModel as y, type AIBatchAnswerValue as z };