interaqt 0.8.3 → 0.8.4

package/agent/.claude/agents/code-generation-handler.md

@@ -162,27 +162,41 @@ git commit -m "feat: Task 3.1.2 - Complete entity and relation implementation"
 - [ ] Ensure all payloads match the documented fields
 - [ ] **🔴 CRITICAL: For query interactions (action: GetAction):**
   - **MUST declare `data` field** - specify the Entity or Relation to query
-  - **SHOULD declare `query` field** if there are predefined filters/fields (use Query.create with QueryItem)
-  - Example:
+  - **SHOULD declare `dataPolicy` field** if there are predefined filters/fields or access restrictions
+  - **⚠️ IMPORTANT: Data Access Scope vs Business Rules**
+    - If `dataConstraints` express **data access scope restrictions** (e.g., "can only view own entities", "can only view specific fields"), use `dataPolicy` NOT `condition`
+    - `dataPolicy` controls what data can be accessed AFTER the operation is permitted
+    - `condition` controls WHETHER the operation can execute (permissions/business rules)
+    - Example of data policy: Restricting visible fields, filtering by ownership
+  - Example with dynamic data policy (user-based filtering):
+    ```typescript
+    const ViewMyOrders = Interaction.create({
+      name: 'ViewMyOrders',
+      action: GetAction,
+      data: Order,
+      dataPolicy: DataPolicy.create({
+        match: function(this: Controller, event: any) {
+          // Only show user's own orders
+          return MatchExp.atom({key: 'owner.id', value:['=', event.user.id]})
+        }
+      })
+    })
+    ```
+  - Example with combined data policy (filtering + field restrictions + pagination):
     ```typescript
     const ViewMyFollowers = Interaction.create({
-      name: 'ViewUsers',
+      name: 'ViewMyFollowers',
       action: GetAction,
       data: User,  // REQUIRED: specify what to query
-      query: Query.create({  // OPTIONAL: predefined query config
-        items: [
-          QueryItem.create({
-            name: 'attributeQuery',
-            value: ['id', 'name', 'email']
-          }),
-          // Use function-based value to add conditional restrictions based on current context user
-          QueryItem.create({
-            name: 'match',
-            value: function(this:Controller, event:any) {
-              return MatchExp.atom({key: 'follow.id', value:['=', event.user.id]})
-            }
-          })
-        ]
+      dataPolicy: DataPolicy.create({
+        // Dynamic filter: only users who follow the current user
+        match: function(this: Controller, event: any) {
+          return MatchExp.atom({key: 'following.id', value:['=', event.user.id]})
+        },
+        // Field restrictions: only expose specific fields
+        attributeQuery: ['id', 'name', 'email'],
+        // Default pagination
+        modifier: { limit: 20, orderBy: { name: 'asc' } }
       })
     })
     ```

package/agent/.claude/agents/error-check-handler.md

@@ -1015,6 +1015,23 @@ const GetUserDonations = Interaction.create({
     ]
   })
 })
+
+// Query interaction with dataPolicy for access control
+const GetMyDonations = Interaction.create({
+  name: 'GetMyDonations',
+  action: GetAction,
+  data: Donation,  // ✅ Entity reference
+  dataPolicy: DataPolicy.create({
+    // ✅ Dynamic filter: users can only see their own donations
+    match: function(this: Controller, event: any) {
+      return MatchExp.atom({key: 'donor.id', value: ['=', event.user.id]})
+    },
+    // ✅ Field restrictions: limit exposed fields
+    attributeQuery: ['id', 'amount', 'createdAt', 'status'],
+    // ✅ Default pagination
+    modifier: { limit: 20, orderBy: { createdAt: 'desc' } }
+  })
+})
 ```
 
 ### Pattern 5: Test Error Checking

package/agent/.claude/agents/frontend-generation-handler.md

@@ -231,7 +231,40 @@ npm run generate-frontend-api
    }
    ```
 
-2. **Reference Existing Components for Patterns:**
+2. **Query Interactions Always Return Arrays:**
+   - Backend query-type interactions always return arrays in `response.data`
+   - To query a specific entity/relation, use the `match` field in the query options (2nd parameter)
+   - Do NOT put match criteria in the payload (1st parameter)
+   
+   ```typescript
+   // ✅ Correct: Use match in query options
+   const response = await apiClient.ViewVideoGenerationStatus(
+     { videoGenerationRequestId: videoId },  // payload
+     {
+       attributeQuery: ['id', 'status', 'videoUrl'],
+       match: {
+         key: 'id',
+         value: ['=', videoId]  // Match condition here
+       }
+     }
+   );
+   const item = response.data[0];  // Extract first item from array
+   
+   // ❌ Wrong: Don't rely on payload for filtering
+   const response = await apiClient.ViewVideoGenerationStatus(
+     { videoGenerationRequestId: videoId }  // This won't filter results
+   );
+   ```
+
+3. **Handling Asynchronous External System Tasks:**
+   - For asynchronous tasks that call external systems, backend typically does NOT implement polling unless explicitly specified in requirements
+   - Backend usually provides a separate API endpoint to trigger status updates
+   - Frontend can call this API to trigger backend status updates
+   - Frontend implementation options:
+     - **Manual trigger**: Add a button in the component for users to manually trigger the status update API
+     - **Automatic polling**: Implement polling in the component (on mount) until the task reaches a completion state
+
+4. **Reference Existing Components for Patterns:**
    - Look at `frontend/src/components/*.tsx` files
    - Follow the same patterns for API client usage
    - Check how error handling is implemented

package/agent/.claude/agents/implement-integration-handler.md

@@ -45,6 +45,27 @@ This applies to BOTH async APIs (with task IDs) and sync APIs (immediate results
 - All integration documentation files MUST be prefixed with current module name from `.currentmodule`
 - Format: `docs/{module}.{integration-name}.integration-design.md`
 
+**🔴 CRITICAL PRINCIPLE: Status Polling Strategy**
+
+**Default Approach: Frontend Polling with Manual Query API**
+
+Backend polling consumes significant server resources. Follow this priority order:
+
+1. **Default (ALWAYS implement)**: Provide manual query API for frontend
+   - Create API endpoint to query external status
+   - Frontend can poll this API at its own pace
+   - Even if polling is needed, frontend handles it unless explicitly stated otherwise
+
+2. **Backend Polling (ONLY if explicitly required)**: Implement server-side polling
+   - ONLY implement if user explicitly requests "backend polling" in requirements
+   - Use with caution due to resource consumption
+   - Example: volcjmeng integration (only because explicitly required)
+
+3. **Webhook (ONLY if both conditions met)**: Implement webhook endpoint
+   - ONLY if external service supports webhook registration
+   - AND user can register webhook themselves
+   - Requires exposing public endpoint for external callbacks
+
 # Core Concepts
 
 ## Interaqt Framework

package/agent/.claude/agents/requirements-analysis-handler.md

@@ -1280,6 +1280,22 @@ git commit -m "feat: Task 1.4 - Complete data concept extraction"
 - Interaction IDs must be semantic names (e.g., "BorrowBook", "ViewAvailableBooks") not codes (e.g., "I001")
 - ❌ If a requirement has role="System", it was incorrectly created - SKIP it, do NOT create interaction
 
+**⚠️ IMPORTANT: Distinguishing Data Access Constraints**
+
+For read-type interaction requirements with access restrictions, distinguish between:
+
+1. **Business Rules** - Constraints on whether the read operation can execute
+   - Example: "Only administrators can view XXX entity"
+   - Controls who can perform the action
+   - Should be specified in the `conditions` field
+
+2. **Data Policy** - Constraints on the scope of data returned
+   - Example: "Can only view own XXX entities" or "Can only view YYY fields of XXX entity"
+   - Controls what data is accessible after the operation is permitted
+   - Should be specified in the `dataConstraints` field
+
+These must be separated as they are implemented differently in subsequent phases.
+
 **⚠️ IMPORTANT: External Integration Interactions**
 
 If Task 1.4 includes API Call entities, design error handling interactions:

package/package.json

@@ -39,7 +39,7 @@
     "sync:agent": "tsx scripts/sync-agent-files.ts",
     "release": "release-it"
   },
-  "version": "0.8.3",
+  "version": "0.8.4",
   "main": "dist/index.js",
   "files": [
     "dist",

package/agent/agentspace/prompt/integration_sub_agent_refactor.md

@@ -1,19 +0,0 @@
-我们的项目所使用的框架是一个叫做 Interaqt 的后端响应式数据框架，它会自动根据应用中的数据变化及响应式数据的定义执行相应的数据变化。它只负责处理一般的业务逻辑中表达的数据逻辑，例如一般业务逻辑中会用到 平均/综合 等计算，还有常见的基于状态机等业务逻辑表达等。对于一些非一般的能力需求，例如 大模型生图、大模型生视频、tts、发送邮件、发送信息、完整支付系统等。它需要借助外部系统/api 来完成。
-我们设计了一个叫做 integration 的概念，专门用来对接当前系统和外部的api/系统。它通过 interaqt 框架提供的数据观察机制，来观察数据变化，根据数据变化来决定如何调用外部的 api。同时通过 webhook 等机制来接受外部的事件，将外部事件同步回系统中，触发响应式的业务逻辑。
-
-我们将 integration 需要集成的功能分成了三种类别：
-1. 调用外部的 api，为了获得一个具体的返回。例如 tts，大模型生图等。
-2. 执行某种副作用，例如发送邮件、发送 im 消息等。
-3. 对接其他有状态的系统，例如支付系统等。
-
-现在我们需要指导 claude code 的 sub agent 合理地识别需要的外部服务以及如何自己实现 integration。
-1. 指导 `.claude/agents/requirements-analysis-handler.md` 在需求分析阶段，正确分析出 integration 的类型。并在相应的输出的文档中，设计一个字段来表达 integration 的类型。
-2. 指导 `.claude/agents/implement-design-handler.md` 在设计数据的时候，根据如下原则进行设计：
-  2.1. 不管是哪种类型，都会涉及到对外部 api 的调用，例如执行副作用，也会有副作用 api 的调用。所以我们应该对每一个 api 的调用都设计一个 `{xxx}APICall` 的 entity，它负责记录这次 api 调用的参数、状态、返回值、调用时间等。
-  2.2. 同时设计一个相应的 integraion event entity，当我们通过 webhook 或者自己通过接口查询到 api 调用状态的变化时，在系统内创建相应的 api call result event 事件。并且将上一步创建的 `{xxx}APICall` entity 的 status 和 data 字段写成基于 integration event entity 的 computation，这样就完整符合了框架的响应式范式。也记录了所有应该记录的数据，增强了系统的健壮性。
-  2.3. 如果当前场景是希望基于这个 integration 获得具体的返回值，那么意味着我们系统内的业务数据对这个 `{xxx}APICall` 的 entity 是有依赖的，应该写成基于 `{xxx}APICall` 的 computation。例如我们的有一个 `Greeting` entity，其中有个 `voiceUrl` property 是需要利用外部 tts 能力将文本转化为语音。那么 `Greeting.voiceUrl` 就应该表达为基于 `{ttsAPICall}` entity 的 computation。如果是纯副作用类型等的调用，就不需要了。注意，这种情况下，还需要建立相应的 entity 和 api call entity 之间的关系，才能查找到正确的数据。
-  2.4. `.claude/agents/implement-design-handler.md` 在做 data-design 的时候，应该明确表达出来：1. 设计的哪些实体是 api call 类型的 entity，哪些实体是 api call result event 实体。2. 系统内的业务数据如果需要 api 的返回结果，那么应该依赖正确的 api call entity。
-3. 指导 `.claude/agents/code-generation-handler.md` 在实现阶段，在写测试用例时，完全可以通过创建正确的 api call result event 来模拟 api 的调用，完整验证系统的内部逻辑的正确性。不需要等到 integration 的真实实现。
-4. 指导 `.claude/agents/error-check-handler.md` 在合适的阶段对 integration 相关的设计做错误检查。
-
-你充分理解上面的所有思路，并且修改相应的 sub agent 文件来达成目标。

package/agent/agentspace/prompt/requirement_analysis_refactor.md

@@ -1,34 +0,0 @@
-在需求分析的过程中，我们已经在 `.claude/agents/requirements-analysis-handle.md` 中提出了一种以最终"读需求"为起点，反向衍生出 创建/修改/删除 需求的方法。
-在实际的探索中发现：用户可能会在输入阶段就按照自己的真实需要描述了一部分流程了，这个流程里面包含了
-
-- 进行增删改查交互的步骤，通常是有依赖顺序的
-- 进行交互的角色
-- 交互对数据产生的具体增删改变化
-例子：在 `requirements/requirements.md` 中，用户直接在描述中叙述如何创建版本 rollback 时数据应该如何变化。这里面就已经包含了："创建版本-回退版本"的具体流程。
-
-这个流程本身也是用户的一种需求，我们需要严格遵照他的指示实现。
-现在，你来将 `.claude/agents/requirements-analysis-handle.md` 完全重写。要求：
-1. 先将 `.claude/agents/requirements-analysis-handle.md` 关于目标补充、数据分析、交互动作定义的步骤、设计的数据结构完全提取出来，这些部分已经很稳定，可以留作复用。
-
-用下面的这些步骤作为重写的分析步骤：
-1. 对用户的输入进行分析，识别出其中的：
-- 目标。通常是和具体软件功能无关，和现实中真实目标相关的描述。例如“管理图书”，“管理员工”，“和好友实时交流”等。
-- 流程。例如 "发出好友申请-收到申请后同意/收到申请后拒绝"。
-- 数据概念。(使用原文档里数据概念)。
-2. 进行常见的目标补充（使用原文档里的方法）。
-3. 进行完整的数据概念设计（复用原文档中的方法）。
-4. 进行流程和交互动作设计。
-  3.1. 优先整合用户描述中的流程。并且看流程达到了哪些目标。
-  3.2. 为没有达到的目标设计流程。
-    3.2.1. 流程是一系列有顺序的交互的总和，其中可以包含可能的分支或者循环。交互的具体定义仍然采用原文档中的定义。
-    3.2.2. 流程的最后仍然应该是一个"读需求"作为结尾，来真正满足目标。但前面需要补充常见的创建等逻辑。
-  3.3. 注意，流程中的每一步应该都是一个交互动作，交互动作要使用原文档中 interactions-design.json 中的数据结构表示。要包含完整 `data.creates`/`data.updates`/`data.deletes`。从用户的输入中直接提取的出来的流程也要完善这些信息。
-5. 设计完流程后。从数据的角度来补充用户可能需要的其他增删改查需求：
-  4.1. 为每一个修改和删除的交互考虑用户作为人类，是否需要经过查看/搜索再进行决策的需求。
-  4.2. 为每一个创建的交互动作考虑，数据在现实中是否允许修改/删除。如果允许就应该增加相应的需求。
-6. 最终产出的 interactions-design.json 仍然使用原文档里的 interaction 数据结构，但以流程为组来组织。
-
-注意，在每一个步骤中，都要给出清晰的数据结构定义，用 json 来写。
-整体用简洁的英语完成文档重写。注意原本文档中的在关键步骤 update docs/{module}.status.json 仍然按照原文档的方式写。
-
-