@harperfast/template-react-ts-studio 1.11.2 → 1.11.4

package/.agents/skills/harper-best-practices/SKILL.md

@@ -84,6 +84,7 @@ See the concrete examples embedded in each rule subsection below (GraphQL schema
 - `logging` — Best practices for logging in Harper, including console capture, the granular logger interface, and programmatic log retrieval.
 - `load-env` — How to load environment variables from .env files into a Harper application using the loadEnv plugin.
 - `v5-upgrade` — Breaking changes and recommended updates when migrating a Harper application to v5.
+- `delegating-to-the-built-in-agent` — How to delegate tasks to Harper's built-in agent via the CLI and the agent operations API.
 
 <!-- END GENERATED INDEX -->
 

package/.agents/skills/harper-best-practices/rules/automatic-apis.md

@@ -6,8 +6,8 @@ metadata:
   sources:
     - reference/v5/rest/overview.md
     - reference/v5/rest/websockets.md
-  sourceCommit: b7fbddadd42eb4487190b650a9abc4bcfeef5819
-  inputHash: 8fcf0cfe190e013e
+  sourceCommit: 3749d0c54be457a2a65d9a63c738a5dc88989ecd
+  inputHash: 6c7013b1307d9f7b
 ---
 
 # Automatic APIs
@@ -20,13 +20,13 @@ Apply this rule when adding REST or WebSocket API access to Harper tables or cus
 
 ## How It Works
 
-1. **Enable the REST plugin**: Add `rest: true` to your application's `config.yaml`. This activates the HTTP REST interface and enables WebSocket support by default.
+1. **Enable the REST plugin**: Add `rest: true` to your application's `config.yaml`. This activates the HTTP REST interface on the application server port (default `9926`) and enables WebSocket support automatically.
 
    ```yaml
    rest: true
    ```
 
-   To configure optional behavior:
+   To configure options explicitly:
 
    ```yaml
    rest:
@@ -34,69 +34,26 @@ Apply this rule when adding REST or WebSocket API access to Harper tables or cus
      webSocket: false # disables automatic WebSocket support (enabled by default)
    ```
 
-2. **Export your resource in the schema**: Tables are not exposed by default. Use the `@export` directive in your schema definition to make a table available as a REST endpoint. The exported name defines the base URL path, served on the application HTTP server port (default `9926`).
+2. **Export your resource in the schema**: Tables are not exposed by default. Use the `@export` directive in your schema definition to expose a table as a REST endpoint. The exported name defines the base URL path.
 
-3. **Use the correct URL structure**: The REST interface follows a consistent path convention.
+3. **Use the correct URL structure**: Target resources using these path conventions:
 
-   | Path                                         | Description                                                                        |
-   | -------------------------------------------- | ---------------------------------------------------------------------------------- |
-   | `/my-resource`                               | Returns a description of the resource (e.g., table metadata)                       |
-   | `/my-resource/`                              | Trailing slash — represents the full collection; append query parameters to search |
-   | `/my-resource/record-id`                     | A specific record identified by its primary key                                    |
-   | `/my-resource/record-id/`                    | Trailing slash — collection of records with the given id prefix                    |
-   | `/my-resource/record-id/with/multiple/parts` | Record id with multiple path segments                                              |
+   | Path                                         | Description                                                 |
+   | -------------------------------------------- | ----------------------------------------------------------- |
+   | `/my-resource`                               | Returns resource metadata                                   |
+   | `/my-resource/`                              | Collection — all records; append query parameters to search |
+   | `/my-resource/record-id`                     | Specific record by primary key                              |
+   | `/my-resource/record-id/`                    | Collection of records with the given id prefix              |
+   | `/my-resource/record-id/with/multiple/parts` | Record id with multiple path segments                       |
 
-4. **Map HTTP methods to operations**: Each HTTP method maps to a resource method and operation.
-   - **GET** — Retrieve a record or search. Calls `get()`.
+4. **Map operations to HTTP methods**: Each HTTP method maps to a resource method:
+   - **GET** — Retrieve a record or search. Calls `get()`. Responses include an `ETag` header; send `If-None-Match` on subsequent requests to receive `304 Not Modified` when unchanged.
+   - **PUT** — Create or replace a record (upsert). Calls `put(record)`. The stored record exactly matches the submitted body; omitted properties are removed.
+   - **POST** — Create a record without specifying a primary key. Calls `post(data)`. The assigned key is returned in the `Location` response header.
+   - **PATCH** — Partially update a record, merging only provided top-level properties. Calls the resource's patch handler. Merge is **shallow** — nested objects are replaced entirely, not deep-merged.
+   - **DELETE** — Delete a record by id or all records matching a query.
 
-     ```
-     GET /MyTable/123
-     GET /MyTable/?name=Harper
-     GET /MyTable/123.propertyName
-     ```
-
-     Responses include an `ETag` header. Clients may send `If-None-Match` to receive `304 Not Modified` when the record is unchanged.
-
-   - **PUT** — Create or replace a record (upsert). Calls `put(record)`. Properties not in the body are removed.
-
-     ```
-     PUT /MyTable/123
-     Content-Type: application/json
-
-     { "name": "some data" }
-     ```
-
-   - **POST** — Create a new record without specifying a primary key. Calls `post(data)`. The assigned key is returned in the `Location` response header.
-
-     ```
-     POST /MyTable/
-     Content-Type: application/json
-
-     { "name": "some data" }
-     ```
-
-   - **PATCH** — Partially update a record, merging only provided properties. Unspecified properties are preserved.
-
-     ```
-     PATCH /MyTable/123
-     Content-Type: application/json
-
-     { "status": "active" }
-     ```
-
-   - **DELETE** — Delete a record or all records matching a query.
-     ```
-     DELETE /MyTable/123
-     DELETE /MyTable/?status=archived
-     ```
-
-5. **Access the auto-generated OpenAPI spec**: Harper generates an OpenAPI specification for all exported resources. Retrieve it at:
-
-   ```
-   GET /openapi
-   ```
-
-6. **Connect via WebSocket**: When `rest` is enabled, WebSocket support is on by default. Connect to a resource URL to subscribe to change events for that resource.
+5. **Connect via WebSocket**: A WebSocket connection to a resource URL subscribes to that resource and streams change events. See [real-time-apps.md](real-time-apps.md) for full real-time patterns.
 
    ```javascript
    let ws = new WebSocket('wss://server/my-resource/341');
@@ -105,13 +62,17 @@ Apply this rule when adding REST or WebSocket API access to Harper tables or cus
    };
    ```
 
-   Connecting to `wss://server/my-resource/341` accesses the `my-resource` resource with record id `341` and subscribes to it. When the record changes or a message is published to it, the WebSocket connection receives the update.
+6. **Implement a custom `connect()` handler** on a resource class to control WebSocket behavior. The method receives `incomingMessages` and must return an async iterable producing messages to send to the client.
+
+7. **Retrieve the OpenAPI spec**: Harper auto-generates an OpenAPI specification for all exported resources, available at:
 
-7. **Implement a custom `connect()` handler**: Override `connect(incomingMessages)` on a resource class to control WebSocket behavior. The method must return an async iterable or generator that produces messages to send to the client.
+   ```
+   GET /openapi
+   ```
 
 ## Examples
 
-**Simple echo server using an async generator**:
+**Simple echo WebSocket server**:
 
 ```javascript
 export class Echo extends Resource {
@@ -123,7 +84,7 @@ export class Echo extends Resource {
 }
 ```
 
-**Using the default `connect()` with event-style access and a timer**:
+**Custom `connect()` using the default iterable with `send()` and `close` event**:
 
 ```javascript
 export class Example extends Resource {
@@ -147,19 +108,26 @@ export class Example extends Resource {
 }
 ```
 
-**Minimal `config.yaml` enabling REST with WebSocket disabled**:
+**Common REST operations**:
+
+```
+GET /MyTable/123
+GET /MyTable/?name=Harper
+PUT /MyTable/123
+PATCH /MyTable/123
+DELETE /MyTable/?status=archived
+```
 
-```yaml
-rest:
-  webSocket: false
+```json
+{ "name": "some data" }
 ```
 
 ## Notes
 
-- Tables must be explicitly exported using `@export` in the schema — they are not exposed by default.
-- `rest: true` is the minimal configuration to enable both REST and WebSocket support. See [real-time-apps.md](real-time-apps.md) for patterns around real-time WebSocket usage.
-- For full query syntax on `GET` and `DELETE` with query parameters, see [querying-rest-apis.md](querying-rest-apis.md).
-- The default `connect()` returns an iterable with a `send(message)` method and a `close` event for cleanup on disconnect.
-- For MQTT over WebSockets, set the sub-protocol header `Sec-WebSocket-Protocol: mqtt`.
-- In distributed environments, non-retained messages are delivered in the order received per node; retained messages (PUT/updated records) keep only the latest-timestamp version as the winning record across the cluster.
-- Use the `Content-Type` request header to specify body format and the `Accept` header to request a specific response format.
+- `rest: true` is the minimal config to enable both REST and WebSocket support. Set `webSocket: false` under the `rest` key to disable WebSocket only.
+- The `@export` directive in the schema is required for any table to appear as a REST endpoint — tables are not exported by default.
+- PATCH merges are shallow (top-level only). Nested objects in the request body replace the entire existing sub-object. Dot-path keys (e.g., `"settings.theme"`) are stored as literal keys, not interpreted as paths.
+- For MQTT over WebSocket, set the sub-protocol header `Sec-WebSocket-Protocol: mqtt`.
+- In distributed environments, non-retained messages are delivered in arrival order; retained messages (PUT/updated records) keep only the latest timestamp as the winning record.
+- For full query syntax on GET and DELETE, see [querying-rest-apis.md](querying-rest-apis.md).
+- For building real-time features with WebSocket subscriptions, see [real-time-apps.md](real-time-apps.md).

package/.agents/skills/harper-best-practices/rules/defining-relationships.md

@@ -6,8 +6,8 @@ metadata:
   sources:
     - reference/v5/database/schema.md#Relationships
     - reference/v5/rest/querying.md#Relationships and Joins
-  sourceCommit: 4fe4c9c95e0974eaa77032f6f10e36fbd8ec64ac
-  inputHash: 6953f507f0cde0f7
+  sourceCommit: 3749d0c54be457a2a65d9a63c738a5dc88989ecd
+  inputHash: fd399fd81a88f13e
 ---
 
 # Defining Relationships Between Tables in Harper
@@ -16,17 +16,17 @@ Instructions for the agent to follow when defining and querying relationships be
 
 ## When to Use
 
-Apply this rule whenever a schema requires linking two tables via a foreign key — for example, modeling shows and networks, products and brands, or orders and items. Use it when queries need to filter or select nested related records using dot-syntax.
+Apply this rule when adding foreign key relationships between schema tables, enabling join queries, or returning nested related records in query results. Use it any time a schema type needs to reference records in another table via a foreign key attribute.
 
 ## How It Works
 
-1. **Use `@relationship(from: attribute)` for many-to-one or many-to-many**: Place this on a field in the current table when the foreign key lives in this table and references the primary key of the target table.
+1. **Use `@relationship(from: attribute)` for many-to-one or many-to-many**: Place this on the field in the table that holds the foreign key. The `from` parameter names the attribute on this table that stores the foreign key referencing the target table's primary key.
 
    ```graphql
    type RealityShow @table @export {
    	id: Long @primaryKey
    	networkId: Long @indexed
-   	network: Network @relationship(from: networkId)
+   	network: Network @relationship(from: networkId) # many-to-one
    	title: String @indexed
    }
 
@@ -36,7 +36,7 @@ Apply this rule whenever a schema requires linking two tables via a foreign key
    }
    ```
 
-   For a many-to-many relationship, make the foreign key an array:
+   If the foreign key attribute is an array, the relationship becomes many-to-many:
 
    ```graphql
    type RealityShow @table @export {
@@ -46,24 +46,24 @@ Apply this rule whenever a schema requires linking two tables via a foreign key
    }
    ```
 
-2. **Use `@relationship(to: attribute)` for one-to-many or many-to-many**: Place this on a field in the current table when the foreign key lives in the target table and references the primary key of this table. The result type must be an array.
+2. **Use `@relationship(to: attribute)` for one-to-many or many-to-many**: Place this on the table whose primary key is referenced by the foreign key in the target table. The `to` parameter names the attribute on the target table that holds the foreign key. The result type **must** be an array.
 
    ```graphql
    type Network @table @export {
    	id: Long @primaryKey
    	name: String @indexed
-   	shows: [RealityShow] @relationship(to: networkId)
+   	shows: [RealityShow] @relationship(to: networkId) # one-to-many
    }
    ```
 
-3. **Use `@relationship(from: attribute, to: attribute)` for foreign key to foreign key joins**: Specify both `from` and `to` when neither side uses the primary key. This is useful for joining on non-primary-key attributes.
+3. **Use `@relationship(from: attribute, to: attribute)` for foreign key to foreign key joins**: Specify both `from` and `to` when neither side uses the primary key. Harper resolves the relationship by searching the target table's `to` attribute for matches using this record's `from` attribute value. The result type must be an array.
 
    ```graphql
    type OrderItem @table @export {
    	id: Long @primaryKey
    	orderId: Long @indexed
    	productSku: Long @indexed
-   	product: Product @relationship(from: productSku, to: sku)
+   	products: [Product] @relationship(from: productSku, to: sku)
    }
 
    type Product @table @export {
@@ -73,15 +73,14 @@ Apply this rule whenever a schema requires linking two tables via a foreign key
    }
    ```
 
-4. **Query across relationships using dot-syntax**: Filter by related table attributes using chained dot notation. This behaves as an INNER JOIN.
+4. **Query across relationships using dot-syntax**: Filter records by related table attributes using chained dot notation. This behaves as an INNER JOIN — only records with a matching related record are returned.
 
    ```
-   GET /RealityShow?network.name=Bravo
    GET /Product/?brand.name=Microsoft
    GET /Brand/?products.name=Keyboard
    ```
 
-5. **Select nested relationship fields with `select()`**: Relationship attributes are not included by default. Use `select()` to include them in results. When selecting without a filter on the related table, this acts as a LEFT JOIN — the relationship property is omitted if the foreign key is null or references a non-existent record.
+5. **Include relationship fields in results using `select()`**: Relationship attributes are not returned by default. Use `select()` to include them, optionally specifying nested fields with `{}`.
 
    ```
    GET /Product/?brand.name=Microsoft&select(name,brand)
@@ -89,77 +88,56 @@ Apply this rule whenever a schema requires linking two tables via a foreign key
    GET /Product/?name=Keyboard&select(name,brand{name,id})
    ```
 
-## Examples
-
-**Many-to-one relationship** — a show belongs to a network:
+   When selecting a relationship without filtering on it, Harper performs a LEFT JOIN — the relationship property is omitted if the foreign key is null or references a non-existent record.
 
-```graphql
-type RealityShow @table @export {
-	id: Long @primaryKey
-	networkId: Long @indexed
-	network: Network @relationship(from: networkId)
-	title: String @indexed
-}
+6. **Model many-to-many without a junction table**: Store an array of foreign key values and use `@relationship(from: ...)` pointing to that array attribute. The array order of the foreign key values is preserved when resolving the relationship.
 
-type Network @table @export {
-	id: Long @primaryKey
-	name: String @indexed
-}
-```
+   ```graphql
+   type Product @table @export {
+   	id: Long @primaryKey
+   	name: String
+   	resellerIds: [Long] @indexed
+   	resellers: [Reseller] @relationship(from: "resellerIds")
+   }
+   ```
 
-Query:
+7. **Define self-referential relationships** for parent-child hierarchies by pointing `@relationship` back at the same table type.
 
-```
-GET /RealityShow?network.name=Bravo
-```
+## Examples
 
-**One-to-many relationship** — a network has many shows:
+**Full schema with bidirectional relationships:**
 
 ```graphql
-type Network @table @export {
+type Product @table @export {
 	id: Long @primaryKey
-	name: String @indexed
-	shows: [RealityShow] @relationship(to: networkId)
+	name: String
+	brandId: Long @indexed
+	brand: Brand @relationship(from: "brandId")
 }
-```
 
-**Many-to-many with array foreign keys** — a product has multiple resellers:
-
-```graphql
-type Product @table @export {
+type Brand @table @export {
 	id: Long @primaryKey
 	name: String
-	resellerIds: [Long] @indexed
-	resellers: [Reseller] @relationship(from: resellerIds)
+	products: [Product] @relationship(to: "brandId")
 }
 ```
 
-Query with nested select:
+**Querying with joins and nested select:**
 
 ```
-GET /Product/?resellers.name=Cool Shop&select(id,name,resellers{name,id})
+GET /Product/?brand.name=Microsoft&select(name,brand{name,id})
+GET /Brand/?products.name=Keyboard
 ```
 
-**Foreign key to foreign key join** — order item joined on SKU:
+**Many-to-many query with nested select:**
 
-```graphql
-type OrderItem @table @export {
-	id: Long @primaryKey
-	orderId: Long @indexed
-	productSku: Long @indexed
-	product: Product @relationship(from: productSku, to: sku)
-}
-
-type Product @table @export {
-	id: Long @primaryKey
-	sku: Long @indexed
-	name: String
-}
+```
+GET /Product/?resellers.name=Cool Shop&select(id,name,resellers{name,id})
 ```
 
 ## Notes
 
-- The `@relationship` directive requires the referenced attribute to be `@indexed` on the foreign key side.
-- Self-referential relationships are supported, enabling parent-child hierarchies within a single table.
-- The array order of foreign key values (e.g., `resellerIds`) is preserved when resolving many-to-many relationships.
-- When using `select()` without a filter on the related table, the join behaves as a LEFT JOIN — missing or null foreign keys result in the relationship property being omitted rather than causing an error.
+- Every attribute named in `from` or `to` must exist on the respective table and be annotated with `@indexed` to support join queries.
+- The `to`-only and `from`+`to` forms both require the result field type to be an array (e.g., `[RealityShow]`).
+- The `from`-only form on a non-array attribute produces a many-to-one relationship; on an array attribute it produces many-to-many.
+- Self-referential relationships are supported for hierarchical data within a single table.

package/.agents/skills/harper-best-practices/rules/delegating-to-the-built-in-agent.md

@@ -0,0 +1,141 @@
+---
+name: delegating-to-the-built-in-agent
+description: How to delegate tasks to Harper's built-in agent via the CLI and the agent operations API.
+metadata:
+  mode: synthesized
+---
+
+# Delegating to the Built-in Agent
+
+Harper 5.2+ ships with a **built-in agent** that runs _inside_ the server, on the main thread
+adjacent to the operations API. Because it runs in-process, it can do things a remote client
+cannot: call the operations API as RBAC-filtered tools, read and write component files under the
+instance's components root, attach the V8 inspector to worker threads to debug and profile them,
+schedule follow-up work, and consult the Harper best-practices skill. You send it a natural-language
+task; it runs a tool-using loop under a super_user identity and reports back.
+
+## When to Use
+
+Delegate to the built-in agent when the work is best done **on the instance itself** rather than
+from your local client:
+
+- Operating on a deployed instance in place — inspect the schema, build or adjust a component,
+  restart, run an operation.
+- Debugging or profiling a running instance — attach to a worker thread, capture a CPU profile,
+  set a logpoint.
+- Handing off a larger, multi-step task to an agent that already has the instance's tools,
+  filesystem, and credentials in context.
+
+Do the work in your own client instead when it's purely local (editing source before deploy) or
+when you don't want a server-side agent making changes.
+
+**Prerequisites:** the target instance must have the agent enabled (an `agent:` config block with
+`enabled: true`) and a configured generative model backend. All agent operations require
+**super_user**.
+
+## How It Works
+
+The lifecycle assumes you have already deployed to and authenticated with the target instance (see
+[deploying-to-harper-fabric.md](deploying-to-harper-fabric.md) — `harper login` stores a token so
+you don't repeat credentials). Delegation reuses that same target and credentials.
+
+There are two equivalent ways to drive the agent.
+
+### Option A — the `harper agent` CLI (simplest)
+
+A thin client over the agent operations API that reuses your stored `harper login` credentials, so
+no connector setup is needed:
+
+```bash
+# One-shot: send a task, print the reply, exit
+harper agent "Describe the schema, then add a price index to the Product table."
+
+# Interactive session (REPL)
+harper agent
+
+# Against a specific remote instead of the logged-in default
+harper agent --target <Application URL> "List the databases and tables."
+```
+
+The CLI polls the run to completion and renders the transcript (tool calls, results, and the
+agent's reply). When a run needs approval for a destructive action, it prompts you inline.
+
+### Option B — the agent operations API (programmatic)
+
+Call the operations API directly (HTTP POST to the ops endpoint, super_user auth). This is the path
+to use from scripts and services.
+
+1. **Start a task** with `agent_prompt`. Returns a `session_id` and a `status`.
+
+   ```bash
+   curl -s -u <user>:<pass> <ops-endpoint> \
+     -H 'Content-Type: application/json' \
+     -d '{"operation":"agent_prompt","message":"Build a Customer table (id, email, name) exported over REST."}'
+   ```
+
+2. **Poll for progress** with `get_agent_session`, passing the `session_id`. The returned session
+   carries the `status`, the `messages` transcript, and any `pendingApprovals`.
+
+   ```bash
+   curl -s -u <user>:<pass> <ops-endpoint> \
+     -H 'Content-Type: application/json' \
+     -d '{"operation":"get_agent_session","session_id":"<id>"}'
+   ```
+
+   Poll until `status` leaves `running` — terminal states are `completed`, `aborted`, and `error`;
+   `awaiting_approval` means it is paused for an approval decision (see step 3).
+
+3. **Approve or deny a paused action.** When the agent enabled configuration has `autoApprove:false`,
+   a destructive tool call pauses the run with a `pendingApprovals[]` entry. Resolve it with
+   `approve_agent_action`, then poll again — approval executes the saved call, denial hands the
+   rejection back to the agent so it can adjust.
+
+   ```bash
+   curl -s -u <user>:<pass> <ops-endpoint> \
+     -H 'Content-Type: application/json' \
+     -d '{"operation":"approve_agent_action","session_id":"<id>","approval_id":"<approval-id>","approved":true}'
+   ```
+
+4. **Continue the conversation** by passing the same `session_id` back into `agent_prompt` with a
+   new `message`. Omit `session_id` to start a fresh session.
+
+Supporting operations: `list_agent_sessions` (recent sessions), `cancel_agent_run` (terminate a
+running or paused session), and `set_agent_config` (adjust `autoApprove`, `allowDestructive`,
+`model`, and related settings on a running instance).
+
+## Examples
+
+**Delegate a build to a deployed Fabric instance and wait for the result:**
+
+```bash
+harper login <Application URL>
+harper agent --target <Application URL> \
+  "Create a Product table (id, name, price) exported over REST, then confirm the endpoint responds."
+```
+
+**Programmatic start-and-poll loop:**
+
+```bash
+SID=$(curl -s -u <user>:<pass> <ops-endpoint> -H 'Content-Type: application/json' \
+  -d '{"operation":"agent_prompt","message":"Add a vector index to the Document.embedding field."}' \
+  | jq -r .session_id)
+
+while [ "$(curl -s -u <user>:<pass> <ops-endpoint> -H 'Content-Type: application/json' \
+  -d "{\"operation\":\"get_agent_session\",\"session_id\":\"$SID\"}" | jq -r .status)" = "running" ]; do
+  sleep 3
+done
+```
+
+## Notes
+
+- **All agent operations require super_user.** Authenticate with `harper login`, which stores a
+  short-lived JWT (operation token) plus a refresh token rather than your password — prefer that
+  over passing credentials inline, and never embed a raw password in scripts or client config.
+- **Approvals are your safety gate.** With `autoApprove:false`, the agent pauses before destructive
+  tools (writing files, deploying, restarting) so an operator decides. Set `autoApprove:true` only
+  when you want unattended runs.
+- **Sessions are single-active.** A session that is `running` or `awaiting_approval` rejects a new
+  `agent_prompt`; resolve the approval or cancel the run first.
+- **MCP alternative.** For MCP-native clients, an instance with MCP enabled exposes the agent as
+  curated MCP tools (`agent_prompt`, `get_agent_session`, `list_agent_sessions`) at the ops API's
+  `/mcp` endpoint — the same delegation loop over the MCP transport instead of raw operations.