@happyvertical/smrt-agents 0.51.3 → 0.51.5

package/AGENTS.md

@@ -250,6 +250,7 @@ const tool = createInvokeAgentTool({
 | `src/agent.ts` | Base Agent class — lifecycle, dispatch, interests, config, opt-in learning trait, multi-instance identity |
 | `src/execute-as-principal.ts` | `executeAsPrincipal` / `PrincipalRun` — run agent work as a persona's bound user (#1888) |
 | `src/report-data-surface.ts` | Principal-bound report discovery, query, lifecycle, drilldown, and export tools (#2462) |
+| `src/smrt-collection-data-surface.ts` | `createSmrtCollectionDataSurfaceDefinition()` — generic registry-driven `SmrtObject` collection to `DataSurfaceDefinition` adapter, with field-policy redaction (schema overrides included), class-aware tenant scope, DNF filter/scope lowering, deny-all short-circuit, query-bound opaque cursors, and offset/cursor paging; callers must keep `maxPageLimit` <= the collection's own row-limit cap (#2905, follow-up #2912) |
 | `src/delegation.ts` | `DelegationEnvelope` — immutable principal + bounded delegation depth (#1892) |
 | `src/invoke-agent.ts` | `invoke-agent` tool, worker executor, completion-dispatch convention, transports (#1892) |
 | `src/playbook-preflight.ts` | `playbooks.preflight` PrincipalTool — advisory per-step verdicts, never a grant (#2590) |

package/README.md

@@ -139,6 +139,13 @@ such as `MessagingSettingsService`.
 | `AgentWithInterestsOptions` | Agent options with interests |
 | `createReportDataSurfaceTools` | Principal-bound report discovery, query, lifecycle, drilldown, and export tools |
 | `ReportDataSurfaceToolsOptions` | Server-owned report catalog and application-host seams |
+| `createSmrtCollectionDataSurfaceDefinition` | Generic registry-driven `SmrtObject` collection → `DataSurfaceDefinition` adapter, with field-policy redaction and offset/cursor paging |
+| `buildDataQuerySchemaForClass` | Memoized `DataQuerySchema` derived from `ObjectRegistry` field metadata for an arbitrary registered class |
+| `executeSmrtCollectionQuery` | Bounded `DataQueryRequest` execution against any `list`/`count`/`facets`-shaped collection |
+| `CreateSmrtCollectionDataSurfaceOptions` | Options for `createSmrtCollectionDataSurfaceDefinition` |
+| `SmrtCollectionQueryCollection` | Structural collection interface the generic adapter executes against |
+| `SmrtCollectionQueryScope` | Trusted, server-derived scope conditions for the generic adapter |
+| `SmrtCollectionDataSurfaceAction` | Declarative row/bulk action catalog entry surfaced via `metadata.actionCatalog` |
 
 ### Report Data-Surface Tools
 
@@ -156,6 +163,51 @@ lock-skipped materializations). Advertised actions are filtered by the live
 principal's tool allow-list and effective permissions; action hosts still
 reauthorize before mutation.
 
+### Generic SmrtObject Collection Data-Surface
+
+`createSmrtCollectionDataSurfaceDefinition()` builds a `DataSurfaceDefinition`
+for an arbitrary registered `SmrtObject` collection (events, ad zones,
+schedules, social accounts, meetings, tasks, …), not just `Content`:
+
+```typescript
+const definition = await createSmrtCollectionDataSurfaceDefinition({
+  qualifiedName: '@myapp/events:Event',
+  collectionName: 'events', // permission-catalog collection
+  collection: async ({ principal }) => getEventsCollection(principal.tenantId),
+  scope: ({ principal }) => ({ tenantId: principal.tenantId }),
+  actions: [{ id: 'cancel', label: 'Cancel', requiresConfirmation: true }],
+});
+```
+
+The schema is derived from `ObjectRegistry.getAllFields()`: `sensitive` and
+`readPermission`-gated fields, transient/non-column-backed fields, the
+class's configured tenant field (from `@TenantScoped()`; unscoped classes get
+no tenant field exclusion or scoping at all), and internal `_`-prefixed
+fields are never declared — the same field-policy boundary
+`@happyvertical/smrt-content`'s ContentList adapter enforces. A host-supplied
+`schema` override is intersected with this same registry-derived exclusion
+set, so it can only narrow, never widen, what is advertised. Execution ANDs
+the tenant read scope and the application `scope` into every branch of the
+caller's filter (`all`/`any`/`not`/condition, lowered to bounded
+disjunctive-normal-form `where` conditions), supports both offset and
+opaque-cursor paging, and never hydrates the full collection. An explicit,
+normalized-empty application `scope` denies all rows and short-circuits
+without calling the collection.
+
+Cursors are opaque and bound to the exact query: they encode `{ binding,
+offset }`, where `binding` fingerprints the normalized request (filter, sort,
+projection) plus the merged tenant/application scope, so a cursor from a
+different query, filter, sort, or tenant is rejected rather than silently
+misapplied. `facets` support defaults from the collection's shape
+(`typeof collection.facets === 'function'` for a static collection; `true`
+for a resolver-backed one, which must set `facets: false` if its resolved
+collection lacks `facets()`). Because `SmrtCollectionQueryCollection` is
+structural, the adapter cannot read a host collection's own row-limit cap —
+set `maxPageLimit` at or below that cap, or a clamped page is detected and
+reported via a result warning rather than corrected. See
+`src/smrt-collection-data-surface.ts` for the full contract and
+`docs/data-surface-conformance.md` for the integration checklist.
+
 ### Server Export (`@happyvertical/smrt-agents/server`)
 
 `createDataSurfaceActionAdapter()` provides server-only preview and confirmed
@@ -193,6 +245,16 @@ persisted envelope field and is never added to the job payload. Worker delivery
 before mutation. The original `job.run()` callback remains available for
 in-process queue adapters.
 
+`createDataSurfaceActionRouteHandlers()` wires a SvelteKit (or any Web
+`Request`/`Response`) route to the adapter: it resolves the principal per
+request, parses the body, and maps every refusal reason to an HTTP status.
+`resolveBulkExplicitIds()` expands a browser-supplied anchor row id into a
+full bulk selection server-side (e.g. "every reference photo for this
+performer") so one idempotency key covers the whole set. See
+[`docs/data-surface-sveltekit-wiring.md`](../../docs/data-surface-sveltekit-wiring.md)
+for the full route → principal → action → queue wiring guide, including the
+refusal-to-status table.
+
 ### UI Export (`@happyvertical/smrt-agents/ui`)
 
 | Export | Description |

package/dist/index.d.ts

@@ -15,6 +15,7 @@ export { AGENT_SCHEDULE_SLUG_BACKFILL, AGENT_SCHEDULE_TABLE, AgentScheduleSlugBa
 export { type CreatePlaybookPreflightToolOptions, createPlaybookPreflightTool, filterPlaybooksByPreflight, PLAYBOOK_PREFLIGHT_FUNCTION_NAME, PLAYBOOK_PREFLIGHT_TOOL_SLUG, playbookStepCollection, playbookStepToolSlug, } from './playbook-preflight.js';
 export { createReportDataSurfaceDefinition, createReportDataSurfaceTools, REPORT_DRILLDOWN_FUNCTION_NAME, REPORT_DRILLDOWN_TOOL_SLUG, REPORT_EXPORT_FUNCTION_NAME, REPORT_EXPORT_TOOL_SLUG, REPORT_QUERY_FUNCTION_NAME, REPORT_QUERY_TOOL_SLUG, REPORT_REFRESH_FUNCTION_NAME, REPORT_REFRESH_TOOL_SLUG, type ReportDataSurfaceAuditEntry, ReportDataSurfaceConfigurationError, type ReportDataSurfaceDefinition, type ReportDataSurfaceExportHost, type ReportDataSurfaceRefreshHost, type ReportDataSurfaceToolsOptions, type ReportDataSurfaceVisibleAck, type ReportDataSurfaceVisibleCommand, ReportDataSurfaceVisibleError, type ReportDataSurfaceVisibleHost, } from './report-data-surface.js';
 export { AgentSchedule, AgentScheduleCollection, type ScheduleStatus, } from './schedule.js';
+export { assertSmrtCollectionQuerySchema, buildDataQuerySchemaForClass, type CreateSmrtCollectionDataSurfaceOptions, clearSmrtCollectionQuerySchemaCache, createSmrtCollectionDataSurfaceDefinition, executeSmrtCollectionQuery, type SmrtCollectionDataSurfaceAction, type SmrtCollectionQueryCollection, type SmrtCollectionQueryScope, } from './smrt-collection-data-surface.js';
 export type { SummaryArticleImage, SummaryArticleOptions, SummaryArticleResult, } from './summary-article.js';
 export { type ResolvedAgentAvailability, TenantAgent, TenantAgentCollection, type TenantAgentStatus, } from './tenant-agent.js';
 export type { AgentStatusType } from './types.js';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}