n8n-nodes-lifespace 0.1.6 → 0.1.8

package/README.md

@@ -66,7 +66,12 @@ Runtime Discovery determines which Spaces, Record Types, fields, queries, Action
 
 ## Generated Record UX
 
-Create/Update keep scalar fields in n8n Resource Mapper while using native n8n controls for LifeSpace calendar-date fields and supported relations. Single relations use a selector; multi-relations use multi-select. List / Query offers typed filter variants for text, enum, boolean, number, date/time and authorized relations, while retaining the raw legacy filter as an expression/compatibility escape hatch.
+The package deliberately exposes two different projections over the same LifeSpace Runtime Discovery semantics:
+
+- **LifeSpace** is the human-authored workflow node. Create/Update fields are generated through n8n Resource Mapper from the selected Record Type, so field type, required state, enum values, calendar dates and supported single relations determine the control automatically. List / Query exposes semantic predicates such as `Status — Is One Of` or `Due Date — After or Equal` instead of asking the workflow author to choose a filter type first. Multi-value relations keep their dedicated multi-select UX.
+- **LifeSpace Agent Tool** is the native AI Tool surface. Its schema is generated for the model: generic queries expose semantic `field` / `operator` / `value` inputs, and the adapter compiles those inputs to the exact transport names published by LifeSpace. Capability Queries consume the grouped schema published by Runtime Discovery.
+
+The human workflow node is not exposed through `usableAsTool`; this avoids maintaining two competing Agent Tool surfaces with different schema behavior.
 
 The node displays the authorized human-readable `spaceName` when present while continuing to submit the stable `spc_*` ID.
 
@@ -76,7 +81,7 @@ Calendar-backed models use canonical `capabilityBindings.calendar` field roles i
 
 ## LifeSpace contract compatibility
 
-This package follows the current LifeSpace Core Kernel `0.32.0` contract family. It consumes Runtime/Discovery semantics only; Eventing configuration and webhook delivery semantics are owned independently by Integration/Eventing `0.1.0`.
+This package follows the current LifeSpace Core Kernel `0.35.0` contract family. It consumes Runtime/Discovery semantics only; Eventing configuration and webhook delivery semantics are owned independently by Integration/Eventing `0.1.0`.
 
 The UX depends on these Kernel capabilities:
 
@@ -95,6 +100,9 @@ The UX depends on these Kernel capabilities:
 - `0.30.0`: explicit paginated Change History collection and Model Control Plane ownership split;
 - `0.31.0`: Integration/Eventing wire representation moves to the independent Integration/Eventing `0.1.0` contract while Core remains the Runtime authority.
 - `0.32.0`: `modelKey` becomes the sole Runtime address and canonical CRUD/Action paths move under `/models/{modelKey}/records`.
+- `0.33.0`: canonical structural `timeRanges` become available in progressive semantic detail without implying an overlap query API.
+- `0.34.0`: explicit `eq/lt/lte/gt/gte` comparison transports, first-class `createdAt` / `updatedAt` envelope comparisons and Core-owned datetime local-date-window conversion become discoverable.
+- `0.35.0`: grouped `query.capabilityQueries` adds the preferred `calendar.window` viewing-window query with explicit IANA viewing timezone and deterministic mixed all-day/timed ordering.
 
 The adapter prefers the `0.27+` progressive flow while configuring a node:
 
@@ -127,16 +135,16 @@ Examples:
 {{$vars.lifeSpaceRecordType}}
 ```
 
-Discovery-backed selectors such as **Space**, **Filter Field**, **Sort Field** and **Action** support the normal n8n pattern: choose a value from the list, or switch the parameter to an expression and provide the corresponding stable ID/key. **Record Type** stores the plain LifeSpace `modelKey`, so a LifeSpace Trigger can feed a Record node directly without a mapping step or an extra Discovery request.
+Discovery-backed selectors such as **Space**, **Sort Field** and **Action** support the normal n8n pattern: choose a value from the list, or switch the parameter to an expression and provide the corresponding stable ID/key. **Record Type** stores the plain LifeSpace `modelKey`, so a LifeSpace Trigger can feed a Record node directly without a mapping step or an extra Discovery request.
 
-The same applies to ordinary values such as Record ID, Search, Filter Value, Return All, Limit, Sort Direction, Cursor, explicit Version, API Method, API Path and JSON Body.
+The same applies to ordinary values such as Record ID, Search, Return All, Limit, Sort Direction, Cursor, explicit Version, API Method, API Path and JSON Body.
 
 Two boundaries are intentional:
 
 - **Resource** and **Operation** are structural node controls and do not accept expressions because they determine which parameter schema and execution path the node has.
-- **Fields** and **Action Input** use n8n's `resourceMapper`. The mapper container is structural, but each generated field value inside it remains expression-capable. This includes relation-backed field values: the UI can offer authorized options while an expression can still supply a stable relation ID or ID list.
+- **Fields**, **Filters**, Capability Query parameters and **Action Input** are generated from Runtime Discovery. Their mapper containers are structural, while generated values remain expression-capable.
 
-For **Filters** and **Sorts**, add the required rows in the node UI and use expressions inside each row's Field/Operator/Value or Field/Direction inputs. The number of rows is treated as workflow structure rather than per-item data. This avoids relying on whole-array expressions for n8n `fixedCollection` parameters.
+In Standard Query, **Filters** is a Discovery-driven Resource Mapper. Adding a filter selects a published semantic predicate such as `Due Date — Before`; n8n then renders the value control from the underlying field type. **Sorts** remains an ordered structural list because sort priority is part of workflow structure rather than per-item data.
 
 If **Record Type** itself varies per input item and those Record Types have different schemas, one discovery-generated mapper cannot safely represent every possible schema at design time. In that case, branch to separate LifeSpace nodes per schema or use **API Request** for a deliberately fully dynamic request.
 
@@ -175,7 +183,7 @@ LifeSpace server defaults are authoritative. A field that is `required` but has
 
 For example, lifecycle state such as Task status can remain server/Action-owned instead of being manually entered by the workflow author.
 
-When Runtime Discovery advertises relation semantics, supported `person`, `person_list`, `record` and `record_list` fields are rendered from the current authorized `{ id, label }` target projection instead of asking the workflow author to type raw identifiers. The displayed value is the canonical LifeSpace reference label, while the workflow payload still stores and submits the stable target ID.
+When Runtime Discovery advertises relation semantics, supported single-value `person` / `record` fields are rendered as selectors from the current authorized `{ id, label }` target projection. Multi-value relations retain the dedicated multi-select control rather than falling back to n8n Resource Mapper's generic JSON array editor. The displayed value is the canonical LifeSpace reference label, while the workflow payload still stores and submits the stable target ID.
 
 Older compatible Discovery responses without relation lookup metadata retain the raw-ID field behavior. The adapter never guesses record labels from conventional fields such as `name`, `title` or `summary`.
 
@@ -195,14 +203,18 @@ If a workflow intentionally needs to bind a known version, add **Concurrency Opt
 
 ### List / Query
 
-The normal UI supports:
+**Query Type** separates ordinary record query UX from capability-owned query semantics:
+
+- **Records** is the normal query surface and exposes optional **Search**, Discovery-driven semantic **Filters**, optional **Advanced Local Date Windows**, generic **Sorts**, **Return All** and **Limit**;
+- each Filter entry represents an allowed field/operator pair published by LifeSpace, for example `Status — Is One Of`, `Due Date — Before` or `Created At — After or Equal`; the adapter compiles the selected semantic predicate to the exact transport parameter published by Discovery;
+- **Capability Query** is offered only when the selected Record Type publishes `query.capabilityQueries`; its selector, parameters and ordering are loaded from Runtime Discovery;
+- **Return All** follows `nextCursor` automatically, while **Limit** bounds a single-page query.
+
+Advanced Local Date Windows are shown separately because a local calendar window is a structured field/start/end/timezone input rather than a scalar predicate. The adapter sends the published date-window parameter names and IANA timezone unchanged; Core owns timezone/DST conversion. Existing persisted legacy `exact/from/to` filters preserve the inclusive `To` behavior.
 
-- optional **Search**;
-- one or more typed **Filters**;
-- **Return All** to follow `nextCursor` automatically;
-- **Limit** when Return All is disabled.
+Generic Search/Filters/Sorts are intentionally hidden in Capability Query mode until LifeSpace publishes machine-readable facet-composability metadata. This prevents the adapter from guessing which generic parameters may be mixed with a grouped capability query.
 
-Use **Sorts → Add Sort** to add zero or more sort criteria in priority order. Sortable model fields use authoritative `title` metadata from Runtime Discovery, while envelope fields such as `createdAt` / `updatedAt` are offered only when Discovery advertises them. Multiple criteria are sent as ordered repeated `sort=field:direction` query parameters.
+Use **Sorts → Add Sort** in Records mode to add zero or more sort criteria in priority order. Sortable model fields use authoritative `title` metadata from Runtime Discovery, while envelope fields such as `createdAt` / `updatedAt` are offered only when Discovery advertises them. Multiple criteria are sent as ordered repeated `sort=field:direction` query parameters.
 
 Advanced **Options** contain manual **Cursor** as an escape hatch.
 
@@ -230,6 +242,30 @@ Paths are relative to the configured API Base URL, for example:
 
 Use normal Record operations when possible because they benefit from Runtime Discovery metadata and n8n-specific UX.
 
+## Use the LifeSpace Agent Tool
+
+Use **LifeSpace Agent Tool** when connecting LifeSpace to an n8n AI Agent. This is a separate native AiTool surface rather than the human workflow node running through `usableAsTool`.
+
+Configure the Tool's structural scope — Space, Record Type and operation — in the node. The Tool then derives its model-facing name, description and input schema from Runtime Discovery, so multiple LifeSpace Tools can distinguish their configured purpose without requiring handwritten descriptions.
+
+For Generic Query, the model receives semantic inputs such as:
+
+```json
+{
+  "search": "food",
+  "filters": [
+    { "field": "status", "operator": "in", "value": ["todo"] },
+    { "field": "dueDate", "operator": "gte", "value": "2026-09-13" }
+  ],
+  "sort": [{ "field": "dueDate", "direction": "asc" }],
+  "limit": 20
+}
+```
+
+The adapter validates those field/operator pairs against Discovery and compiles them to the exact LifeSpace query transport. The model does not need to know transport names such as `dueDate.gte`. Local date windows are likewise semantic inputs and Core remains responsible for timezone/DST conversion.
+
+Create/Update schemas are generated from writable model fields. Optional fields that the model does not provide are omitted rather than synthesized as empty values. Actions and Capability Queries remain metadata-driven, and adding a future Record Type does not require a model-specific `create_*` or `query_*` node implementation.
+
 ## Use the LifeSpace Trigger
 
 The **LifeSpace Trigger** receives signed LifeSpace Domain Event webhooks.
@@ -265,11 +301,12 @@ Webhook Endpoint / Event Subscription creation is intentionally not performed by
 
 - **LifeSpace API** credential for API authentication and Runtime Discovery;
 - **LifeSpace Webhook Signing** credential for endpoint-scoped inbound HMAC verification;
-- **LifeSpace** node with discovery-driven Record operations plus advanced API Request;
+- **LifeSpace** human workflow node with Discovery-driven Record operations plus advanced API Request;
+- **LifeSpace Agent Tool** native AiTool with Discovery-driven semantic schemas;
 - **LifeSpace Trigger** with signed multi-Record-Type Domain Event filtering;
-- dynamic Space, Record Type, field, relation target, query, Action and Action Input UI based on progressive Runtime Discovery.
+- shared thin adapter projection from LifeSpace Runtime Discovery into human n8n controls and model-facing Tool schemas.
 
-LifeSpace remains authoritative for validation, authorization, defaults, Mutation Authority, Action semantics, relation semantics and event contracts. Runtime Discovery and Relation Target Lookup are current capability/reference projections, not execution-authorization proofs.
+LifeSpace remains authoritative for validation, authorization, defaults, Mutation Authority, Action semantics, query/time semantics, relation semantics and event contracts. Runtime Discovery and Relation Target Lookup are current capability/reference projections, not execution-authorization proofs.
 
 ## Architecture boundary
 
@@ -277,6 +314,8 @@ LifeSpace is the source of truth for Identity, Authority, Shared Reality semanti
 
 LifeSpace does not depend on n8n. n8n is one optional orchestration/integration runtime consuming LifeSpace APIs and events.
 
+The human Workflow node and native Agent Tool are separate presentation projections over the same LifeSpace semantics. Shared code in this package only translates Discovery into n8n-specific UI/schema/transport; it does not redefine domain rules.
+
 The adapter does not use privileged model-admin endpoints for ordinary workflow discovery and does not copy Model Definitions into this repository.
 
 ## Development
@@ -319,4 +358,4 @@ The adapter now consumes generic `person`, `person_list`, `record` and `record_l
 
 ## License
 
-MIT
+MIT

package/dist/nodes/LifeSpace/LifeSpace.node.d.ts

@@ -16,6 +16,13 @@ export declare class LifeSpace implements INodeType {
             getBooleanFilterableFields(this: ILoadOptionsFunctions): Promise<INodePropertyOptions[]>;
             getNumericFilterableFields(this: ILoadOptionsFunctions): Promise<INodePropertyOptions[]>;
             getTemporalFilterableFields(this: ILoadOptionsFunctions): Promise<INodePropertyOptions[]>;
+            getNumericComparisonFields(this: ILoadOptionsFunctions): Promise<INodePropertyOptions[]>;
+            getTemporalComparisonFields(this: ILoadOptionsFunctions): Promise<INodePropertyOptions[]>;
+            getComparisonOperatorsForCurrentField(this: ILoadOptionsFunctions): Promise<INodePropertyOptions[]>;
+            getLocalDateWindowFields(this: ILoadOptionsFunctions): Promise<INodePropertyOptions[]>;
+            getQueryModes(this: ILoadOptionsFunctions): Promise<INodePropertyOptions[]>;
+            getCapabilityQueries(this: ILoadOptionsFunctions): Promise<INodePropertyOptions[]>;
+            getSemanticSorts(this: ILoadOptionsFunctions): Promise<INodePropertyOptions[]>;
             getPersonFilterableFields(this: ILoadOptionsFunctions): Promise<INodePropertyOptions[]>;
             getEnumValuesForCurrentFilter(this: ILoadOptionsFunctions): Promise<INodePropertyOptions[]>;
             getSortableFields(this: ILoadOptionsFunctions): Promise<INodePropertyOptions[]>;
@@ -23,6 +30,7 @@ export declare class LifeSpace implements INodeType {
         resourceMapping: {
             getRecordFields(this: ILoadOptionsFunctions): Promise<ResourceMapperFields>;
             getActionInputFields(this: ILoadOptionsFunctions): Promise<ResourceMapperFields>;
+            getSemanticQueryInputFields(this: ILoadOptionsFunctions): Promise<ResourceMapperFields>;
         };
     };
     execute(this: IExecuteFunctions): Promise<INodeExecutionData[][]>;