interaqt 0.6.1 → 0.6.3

package/agent/agentspace/knowledge/generator/api-reference.md

@@ -2799,6 +2799,137 @@ new Controller({
 
 ⚠️ **IMPORTANT**: Controller does NOT accept a computations parameter. All computations should be defined within the `computation` field of Entity/Relation/Property definitions. The 6th parameter `dict` is for global dictionary definitions (Dictionary.create), not for computation definitions.
 
+### RecordMutationSideEffect
+
+RecordMutationSideEffect allows you to execute custom logic when records are created, updated, or deleted within interaction contexts. It's useful for triggering external operations, logging, or custom business logic in response to data changes.
+
+**Syntax**
+```typescript
+RecordMutationSideEffect.create(config: RecordMutationSideEffectConfig): RecordMutationSideEffectInstance
+```
+
+**Parameters**
+- `config.name` (string, required): Unique name for the side effect
+- `config.record` (object, required): Target record configuration
+  - `record.name` (string, required): Entity or relation name to monitor
+- `config.content` (function, required): Async function executed when mutation occurs
+  ```typescript
+  async (event: RecordMutationEvent) => Promise<any>
+  ```
+
+**RecordMutationEvent Structure**
+```typescript
+type RecordMutationEvent = {
+    recordName: string                    // Entity/relation name
+    type: 'create' | 'update' | 'delete' // Mutation type
+    record?: { id: string, ... }         // New/current record (for create/update)
+    oldRecord?: { id: string, ... }      // Previous record (for update/delete)
+    keys?: string[]                      // Changed fields (for update)
+}
+```
+
+**Important Notes**
+- RecordMutationSideEffect **only** triggers within interaction execution context
+- Direct storage operations (e.g., `controller.system.storage.create()`) do **NOT** trigger side effects
+- All side effects registered for an entity are called on any mutation of that entity
+- Side effects run after the storage operation completes
+- Side effect errors are captured but don't fail the interaction
+
+**Examples**
+
+```typescript
+// Log user creation events
+const userCreatedLogger = RecordMutationSideEffect.create({
+    name: 'userCreatedLogger',
+    record: { name: 'User' },
+    content: async (event) => {
+        if (event.type === 'create') {
+            console.log('New user created:', event.record?.id);
+            // Send welcome email, update analytics, etc.
+            return { logged: true, userId: event.record?.id };
+        }
+        return null;
+    }
+});
+
+// Audit trail for data changes
+const auditLogger = RecordMutationSideEffect.create({
+    name: 'auditLogger',
+    record: { name: 'Order' },
+    content: async (event) => {
+        const audit = {
+            action: event.type,
+            entityId: event.record?.id || event.oldRecord?.id,
+            timestamp: new Date().toISOString(),
+            changes: event.type === 'update' ? {
+                before: event.oldRecord,
+                after: event.record,
+                fields: event.keys
+            } : null
+        };
+        
+        // Store audit log (pseudo-code)
+        await auditService.log(audit);
+        return { audited: true };
+    }
+});
+
+// Cache invalidation on updates
+const cacheInvalidator = RecordMutationSideEffect.create({
+    name: 'cacheInvalidator',
+    record: { name: 'Product' },
+    content: async (event) => {
+        if (event.type === 'update' || event.type === 'delete') {
+            const productId = event.record?.id || event.oldRecord?.id;
+            await cacheService.invalidate(`product:${productId}`);
+            return { invalidated: true, productId };
+        }
+        return null;
+    }
+});
+
+// Using in Controller
+const controller = new Controller({
+    system: system,
+    entities: [User, Order, Product],
+    relations: [],
+    interactions: [CreateUserInteraction, UpdateOrderInteraction],
+    recordMutationSideEffects: [
+        userCreatedLogger,
+        auditLogger,
+        cacheInvalidator
+    ]
+});
+
+// When interaction is called, side effects are triggered
+const result = await controller.callInteraction('createUser', {
+    user: { id: 'admin' },
+    payload: { name: 'John', email: 'john@example.com' }
+});
+
+// Access side effect results
+if (result.sideEffects?.userCreatedLogger?.error) {
+    console.warn('Logger failed:', result.sideEffects.userCreatedLogger.error);
+} else {
+    console.log('Logger result:', result.sideEffects.userCreatedLogger.result);
+}
+```
+
+**Common Use Cases**
+1. **Audit Logging**: Track all changes to sensitive data
+2. **External System Sync**: Update external systems when data changes
+3. **Cache Management**: Invalidate caches on data mutations
+4. **Notifications**: Send notifications when specific events occur
+5. **Analytics**: Track user actions and data changes
+6. **Cleanup Tasks**: Perform cleanup when records are deleted
+
+**Best Practices**
+1. Filter by event type within the content function if needed
+2. Handle errors gracefully - side effect failures shouldn't break the main operation
+3. Keep side effects lightweight to avoid impacting performance
+4. Use descriptive names for debugging
+5. Return meaningful results for monitoring
+
 **Main Methods**
 
 #### setup(install?: boolean)
@@ -2807,11 +2938,17 @@ Initialize system.
 await controller.setup(true) // Create database tables
 ```
 
-#### callInteraction(interactionName: string, args: InteractionEventArgs)
-Call interaction.
+#### callInteraction(interactionName: string, args: InteractionEventArgs, activityName?: string, activityId?: string)
+Call interaction or activity interaction.
 
 **Note about ignorePermission**: When `controller.ignorePermission` is set to `true`, this method will bypass all condition checks, user validation, and payload validation defined in the interaction.
 
+**Parameters**
+- `interactionName`: The name of the interaction to call
+- `args`: The interaction event arguments containing user and payload
+- `activityName` (optional): The name of the activity when calling an activity interaction
+- `activityId` (optional): The ID of the activity instance when calling an activity interaction
+
 **Return Type**
 ```typescript
 type InteractionCallResponse = {
@@ -2842,7 +2979,7 @@ type InteractionCallResponse = {
 }
 ```
 
-**Example**
+**Example - Regular Interaction**
 ```typescript
 const result = await controller.callInteraction('createPost', {
     user: { id: 'user1' },
@@ -2864,14 +3001,13 @@ if (result.sideEffects?.emailNotification?.error) {
 }
 ```
 
-#### callActivityInteraction(activityName: string, interactionName: string, activityId: string, args: InteractionEventArgs)
-Call interaction within activity.
+**Example - Activity Interaction**
 ```typescript
-const result = await controller.callActivityInteraction(
-    'OrderProcess',
+const result = await controller.callInteraction(
     'confirmOrder',
-    'activity-instance-1',
-    { user: { id: 'user1' }, payload: { orderData: {...} } }
+    { user: { id: 'user1' }, payload: { orderData: {...} } },
+    'OrderProcess',
+    'activity-instance-1'
 )
 ```
 

package/agent/agentspace/knowledge/generator/test-implementation.md

@@ -35,7 +35,19 @@ expect(result.error).toBeUndefined()
 
 ## callInteraction Return Value
 
-The `controller.callInteraction()` method returns a `InteractionCallResponse` object with the following structure:
+The `controller.callInteraction()` method is used for both regular interactions and activity interactions. 
+
+**Method Signature:**
+```typescript
+callInteraction(
+  interactionName: string, 
+  args: InteractionEventArgs, 
+  activityName?: string,    // Optional: for activity interactions
+  activityId?: string       // Optional: for activity interactions
+): Promise<InteractionCallResponse>
+```
+
+The method returns a `InteractionCallResponse` object with the following structure:
 
 ```typescript
 type InteractionCallResponse = {
@@ -232,11 +244,11 @@ expect(publishResult.error).toBeUndefined()
 expect(publishResult.sideEffects?.emailNotification?.result).toBe('sent')
 
 // 4. Activity interactions return activityId
-const activityResult = await controller.callActivityInteraction(
-  'ApprovalWorkflow', 
-  'StartApproval', 
-  undefined, 
-  {...}
+const activityResult = await controller.callInteraction(
+  'StartApproval',
+  {...},
+  'ApprovalWorkflow',
+  undefined
 )
 const activityId = activityResult.context?.activityId
 ```

package/agent/agentspace/knowledge/usage/05-interactions.md

@@ -1205,20 +1205,20 @@ if (createPostInteraction) {
 
 ```javascript
 // Execute interaction as part of an activity
-const result = await controller.callActivityInteraction(
-  'OrderProcess',        // activity name
+const result = await controller.callInteraction(
   'processPayment',      // interaction name
-  'activity-instance-id',// activity instance ID
   {
     user: { id: 'user123' },
     payload: { /* ... */ }
-  }
+  },
+  'OrderProcess',        // activity name (optional)
+  'activity-instance-id' // activity instance ID (optional)
 );
 ```
 
 ## Error Handling
 
-> **Important**: The interaqt framework automatically catches and handles all errors, never throwing uncaught exceptions. All errors are returned through the `error` field in the return value of `callInteraction` or `callActivityInteraction`. Therefore, **DO NOT use try-catch to test error cases**, instead check the `error` field in the return value.
+> **Important**: The interaqt framework automatically catches and handles all errors, never throwing uncaught exceptions. All errors are returned through the `error` field in the return value of `callInteraction`. Therefore, **DO NOT use try-catch to test error cases**, instead check the `error` field in the return value.
 
 ### Parameter Validation Errors
 

package/agent/agentspace/knowledge/usage/13-testing.md

@@ -150,12 +150,12 @@ const result = await controller.callInteraction(interactionName: string, args: {
   payload?: { [key: string]: any }           // Optional payload
 })
 
-// Call activity interaction
-const result = await controller.callActivityInteraction(
-  activityName: string,
+// Call activity interaction (using the same callInteraction method)
+const result = await controller.callInteraction(
   interactionName: string,
-  activityId: string,
-  args: InteractionEventArgs
+  args: InteractionEventArgs,
+  activityName: string,    // Optional: for activity interactions
+  activityId: string       // Optional: for activity interactions
 )
 ```
 

package/agent/agentspace/knowledge/usage/14-api-reference.md

@@ -1200,8 +1200,16 @@ Initialize system.
 await controller.setup(true) // Create database tables
 ```
 
-#### callInteraction(interactionName: string, args: InteractionEventArgs)
-Call interaction.
+#### callInteraction(interactionName: string, args: InteractionEventArgs, activityName?: string, activityId?: string)
+Call interaction or activity interaction.
+
+**Parameters:**
+- `interactionName`: The name of the interaction to call
+- `args`: The interaction event arguments containing user and payload
+- `activityName` (optional): The name of the activity when calling an activity interaction
+- `activityId` (optional): The ID of the activity instance when calling an activity interaction
+
+**Example - Regular Interaction:**
 ```typescript
 const result = await controller.callInteraction('createPost', {
     user: { id: 'user1' },
@@ -1209,17 +1217,17 @@ const result = await controller.callInteraction('createPost', {
 })
 ```
 
-#### callActivityInteraction(activityName: string, interactionName: string, activityId: string, args: InteractionEventArgs)
-Call interaction within activity.
+**Example - Activity Interaction:**
 ```typescript
-const result = await controller.callActivityInteraction(
-    'OrderProcess',
+const result = await controller.callInteraction(
     'confirmOrder',
-    'activity-instance-1',
-    { user: { id: 'user1' }, payload: { orderData: {...} } }
+    { user: { id: 'user1' }, payload: { orderData: {...} } },
+    'OrderProcess',
+    'activity-instance-1'
 )
 ```
 
+
 ### System
 
 System abstract interface that defines basic services like storage and logging.

package/agent/agentspace/prompt/requirement_analysis_refactor.md

@@ -0,0 +1,34 @@
+在需求分析的过程中，我们已经在 `.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 STATUS.json 仍然按照原文档的方式写。
+
+