interaqt 0.8.3 → 0.8.5

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

@@ -205,6 +205,7 @@ npm run generate-frontend-api
 - **Framework**: React + TypeScript
 - **Build Tool**: Vite
 - **Styling**: Tailwind CSS
+- **Routing**: React Router
 - **State Management**: React Context (for API client and global state)
 
 **Project Structure:**
@@ -231,7 +232,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
@@ -274,6 +308,22 @@ npm run generate-frontend-api
    - Test on different screen sizes
    - Ensure mobile-friendly layouts
 
+7. **Modular Navigation:**
+   - **Module Entry Points**: Create a main navigation menu listing all modules
+   - **Route Organization**: Structure routes with module prefixes (e.g., `/donate/*`, `/livestream/*`)
+   - **Active Module Indicator**: Highlight current module in navigation menu
+   - **Breadcrumb Navigation**: Show module name → page hierarchy
+   - **Module Switching**: Enable seamless navigation between modules
+   - **Example Structure**:
+     ```typescript
+     // Main App Router
+     <Routes>
+       <Route path="/" element={<ModuleSelector />} />
+       <Route path="/donate/*" element={<DonateModule />} />
+       <Route path="/livestream/*" element={<LivestreamModule />} />
+     </Routes>
+     ```
+
 **🔴 CRITICAL: Completeness Check**
 
 Before marking Step 4 complete, verify:

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
@@ -281,6 +302,7 @@ interface IIntegration {
     setup?(controller: Controller): Promise<any>  // Setup phase with controller access
     createSideEffects(): RecordMutationSideEffect[]  // Listen to data mutations and create events
     createAPIs?(): APIs              // Expose custom APIs (e.g., webhook endpoints)
+    createMiddlewares?(): MiddlewareHandler[]  // Optional: Create HTTP middleware for request processing
 }
 ```
 
@@ -292,6 +314,63 @@ interface IIntegration {
   1. Webhook endpoints to receive external system callbacks
   2. Manual trigger/query APIs for status checks and retries
   3. Frontend support APIs (e.g., pre-signed URLs for uploads)
+- **createMiddlewares()**: Optional method to create HTTP middleware for request processing (e.g., authentication, authorization, request validation)
+
+**🔴 CRITICAL: Separation Between API Layer and Integration Layer**
+
+**API File Responsibilities** (`integrations/{name}/externalApi.ts` or `integrations/{name}/volcApi.ts`):
+- Construct HTTP requests according to external API documentation
+- Call external APIs and return raw responses
+- **NO data transformation** - return data as-is from external system
+- Define **strict TypeScript types** based on official API documentation:
+  - Input parameter types (exactly matching API requirements)
+  - Output response types (exactly matching API responses)
+- Handle only HTTP-level errors (network failures, status codes)
+
+**Integration File Responsibilities** (`integrations/{name}/index.ts`):
+- Call API file methods to interact with external system
+- **Transform external API responses** into internal event format
+- Map external data structures to business event entity fields
+- Create integration events following unified sequence
+- Handle business-level error scenarios
+
+**Example:**
+```typescript
+// ❌ WRONG: API file transforms data
+// integrations/tts/externalApi.ts
+export async function callTTSApi(params: TTSParams): Promise<{ audioUrl: string }> {
+  const response = await fetch(...)
+  const data = await response.json()
+  return { audioUrl: data.result.url }  // ❌ Transformation in API file
+}
+
+// ✅ CORRECT: API file returns raw response
+// integrations/tts/externalApi.ts
+export type TTSApiResponse = {
+  taskId: string
+  status: string
+  result?: {
+    url: string
+    duration: number
+  }
+}
+
+export async function callTTSApi(params: TTSParams): Promise<TTSApiResponse> {
+  const response = await fetch(...)
+  return await response.json()  // ✅ Raw response with strict types
+}
+
+// ✅ CORRECT: Integration file transforms data
+// integrations/tts/index.ts
+const apiResponse = await callTTSApi(requestParams)
+
+// Transform to internal event format
+await this.createIntegrationEvent(controller, apiCall.id, apiResponse.taskId, 'initialized', {
+  taskId: apiResponse.taskId,           // Map to event fields
+  status: apiResponse.status,
+  audioUrl: apiResponse.result?.url     // Extract what business needs
+}, null)
+```
 
 # Task 4: Integration Implementation
 
@@ -810,14 +889,26 @@ mkdir -p integrations/{integration-name}
 
 ### 4.4.2 Create External API Wrapper (if no SDK)
 
+**🔴 CRITICAL: API File Responsibilities**
+
+This file MUST:
+- Return raw API responses without transformation
+- Define strict TypeScript types matching official API documentation
+- Handle only HTTP-level errors
+
+This file MUST NOT:
+- Transform data to internal event format (that's integration file's job)
+- Create any integration events
+- Handle business logic
+
 Create `integrations/{integration-name}/externalApi.ts`:
 
 ```typescript
 /**
  * External API wrapper for {System Name}
  * 
- * This module encapsulates all external API calls to keep the integration
- * logic clean and testable.
+ * CRITICAL: This file returns raw API responses with strict types.
+ * NO data transformation - integration file handles that.
  */
 
 export type ExternalApiConfig = {
@@ -825,16 +916,37 @@ export type ExternalApiConfig = {
   baseUrl?: string
 }
 
+/**
+ * Request parameters - MUST match external API documentation exactly
+ */
 export type RequestParams = {
-  // Define request parameters
+  // Define according to official API docs
+  param1: string
+  param2: number
+  // ... more parameters
 }
 
+/**
+ * Response data - MUST match external API response exactly
+ */
 export type ResponseData = {
-  // Define response structure
+  // Define according to official API docs
+  taskId: string
+  status: 'pending' | 'processing' | 'completed' | 'failed'
+  result?: {
+    // Define result structure from API docs
+    data: any
+  }
+  error?: {
+    code: string
+    message: string
+  }
 }
 
 /**
  * Call external API
+ * 
+ * Returns raw API response - NO transformation
  */
 export async function callExternalApi(
   params: RequestParams,
@@ -861,7 +973,8 @@ export async function callExternalApi(
       throw new Error(`API call failed: ${response.statusText}`)
     }
 
-    const data = await response.json()
+    // Return raw response - integration file will transform it
+    const data: ResponseData = await response.json()
     return data
   } catch (error: any) {
     console.error('[ExternalAPI] Call failed:', error.message)
@@ -871,12 +984,26 @@ export async function callExternalApi(
 
 /**
  * Query external status
+ * 
+ * Returns raw status response - NO transformation
  */
 export async function queryExternalStatus(
   taskId: string,
   config?: ExternalApiConfig
 ): Promise<ResponseData> {
-  // Similar implementation
+  // Similar implementation - return raw response
+  const apiKey = config?.apiKey
+  const baseUrl = config?.baseUrl
+  
+  const response = await fetch(`${baseUrl}/v1/status/${taskId}`, {
+    method: 'GET',
+    headers: {
+      'Authorization': `Bearer ${apiKey}`
+    }
+  })
+
+  const data: ResponseData = await response.json()
+  return data  // Raw response
 }
 ```
 
@@ -891,8 +1018,9 @@ Create `integrations/{integration-name}/index.ts`:
  * Purpose: {Brief description}
  * 
  * Features:
- * - Listen to {Entity} mutations and trigger external API calls
- * - Convert external status updates to internal events
+ * - Listen to APICall entity creation and trigger external API calls
+ * - Transform external API responses to internal event format
+ * - Create integration events following unified sequence
  * - Provide manual status refresh API
  * - Factory function pattern for configuration flexibility
  */
@@ -1086,31 +1214,42 @@ export function create{IntegrationName}Integration(config: {IntegrationName}Conf
                 requestParams
               })
               
-              // Step 2: Call external API and create unified event sequence
+              // Step 2: Call external API (returns raw response with strict types)
               try {
-                const result = await callExternalApi(requestParams)
+                const apiResponse = await callExternalApi(requestParams)
+                // apiResponse has type ResponseData from API file
                 
+                // Step 3: Transform external response to internal event format
                 // Determine externalId: use API's task ID or generate one
-                const externalId = result.taskId || result.id || crypto.randomUUID()
+                const externalId = apiResponse.taskId 
                 
                 console.log('[{IntegrationName}] External API called', {
                   apiCallId: apiCall.id,
                   externalId,
-                  hasTaskId: !!(result.taskId || result.id)
+                  hasTaskId: !!(apiResponse.taskId)
                 })
                 
+                // Step 4: Transform and create 'initialized' event
+                // Map external fields to internal event format
+                const eventData = {
+                  taskId: apiResponse.taskId,
+                  status: apiResponse.status,
+                  // Map other fields as needed for business logic
+                  rawResponse: apiResponse  // Keep raw response if needed
+                }
+                
                 // ALWAYS create 'initialized' event with both entityId and externalId
                 await self.createIntegrationEvent(
                   this,
                   apiCall.id,              // entityId - APICall's id
                   externalId,              // externalId - task ID or generated UUID
                   'initialized',
-                  result,
+                  eventData,               // Transformed data, not raw response
                   null
                 )
                 
                 // For sync APIs (no task ID): immediately create processing and completed events
-                if (!result.taskId && !result.id) {
+                if (!apiResponse.taskId) {
                   // Immediately create processing event
                   await self.createIntegrationEvent(
                     this,
@@ -1121,19 +1260,26 @@ export function create{IntegrationName}Integration(config: {IntegrationName}Conf
                     null
                   )
                   
-                  // Immediately create completed event
+                  // Transform completion data
+                  const completedData = {
+                    status: 'completed',
+                    result: apiResponse.result,
+                    // Map other completion fields
+                  }
+                  
+                  // Immediately create completed event with transformed data
                   await self.createIntegrationEvent(
                     this,
                     null,
                     externalId,
                     'completed',
-                    result,
+                    completedData,         // Transformed data
                     null
                   )
                   
                   console.log('[{IntegrationName}] Sync API completed with unified event sequence')
                 }
-                // For async APIs: result will come later via webhook or polling
+                // For async APIs: status will come later via webhook or polling
                 
               } catch (error: any) {
                 console.error('[{IntegrationName}] External API call failed', {
@@ -1191,10 +1337,11 @@ export function create{IntegrationName}Integration(config: {IntegrationName}Conf
             apiCallId: string
           }) {
             try {
-              await self.checkAndUpdateStatus(params.apiCallId)
+              const apiResponse = await self.checkAndUpdateStatus(params.apiCallId)
               return {
                 success: true,
-                message: 'Status check triggered, integration event created'
+                message: 'Status check triggered, integration event created',
+                response: apiResponse
               }
             } catch (error: any) {
               console.error('[{IntegrationName}] Failed to query status', {
@@ -1322,25 +1469,36 @@ export function create{IntegrationName}Integration(config: {IntegrationName}Conf
         throw new Error(`No external ID found for APICall: ${apiCallId}`)
       }
 
-      // Query external system
-      const result = await queryExternalStatus(externalId)
+      // Query external system (returns raw response)
+      const apiResponse = await queryExternalStatus(externalId)
 
       console.log('[{IntegrationName}] Status checked', {
         apiCallId,
         externalId,
-        status: result.status
+        status: apiResponse.status
       })
 
+      // Transform external response to internal event format
+      const eventType = apiResponse.status  // Map external status to event type
+      const eventData = apiResponse.result ? {
+        status: apiResponse.status,
+        result: apiResponse.result,
+        // Map other fields as needed
+      } : null
+      const errorMessage = apiResponse.error?.message || null
+
       // Create integration event based on status
       // entityId is null because APICall already exists (not 'initialized' event)
       await this.createIntegrationEvent(
         this.controller,
         null,              // entityId - not needed for status updates
         externalId,        // externalId - to match with existing APICall
-        result.status,     // eventType - 'processing' | 'completed' | 'failed'
-        result.data || null,
-        result.error || null
+        eventType,         // eventType - 'processing' | 'completed' | 'failed'
+        eventData,         // Transformed data, not raw response
+        errorMessage       // Extracted error message
       )
+
+      return apiResponse
     }
   }
 }
@@ -1666,6 +1824,101 @@ createAPIs() {
 }
 ```
 
+## Integration Middleware
+
+**🔴 CRITICAL: Middleware for Request Processing**
+
+Integrations can provide HTTP middleware to handle cross-cutting concerns like authentication, authorization, request validation, logging, etc.
+
+**When to use middleware:**
+- Authentication and authorization (e.g., JWT verification)
+- Request/response transformation
+- Logging and monitoring
+- Rate limiting
+- CORS handling
+- Custom header processing
+
+**Middleware execution:**
+- Middleware runs BEFORE API handlers
+- Can access and modify request context
+- Can short-circuit request processing
+- Can inject context data for API handlers
+
+**Example: Authentication Middleware**
+
+```typescript
+export function createAuthIntegration(config: AuthIntegrationConfig) {
+  return class AuthIntegration implements IIntegration {
+    createMiddlewares(): MiddlewareHandler[] {
+      return [
+        async (c, next) => {
+          // Extract token from multiple sources
+          let token: string | undefined
+          const authToken = c.req.query('authToken')
+          const authHeader = c.req.header('authorization')
+          const cookieHeader = c.req.header('cookie')
+
+          if (authToken) {
+            token = authToken
+          } else if (authHeader?.startsWith('Bearer ')) {
+            token = authHeader.substring(7)
+          } else if (cookieHeader) {
+            const allCookies: Record<string, string> = {}
+            cookieHeader.split(';').forEach((cookie) => {
+              const [name, value] = cookie.trim().split('=')
+              if (name && value) {
+                allCookies[name] = decodeURIComponent(value)
+              }
+            })
+            token = allCookies.token
+          }
+
+          // Verify token and inject userId into context
+          if (token) {
+            try {
+              const decoded = await verify(token, jwtSecret) as any
+              c.set('userId', decoded.userId)
+            } catch (err) {
+              console.log('Invalid token', err)
+            }
+          }
+
+          await next()
+        }
+      ]
+    }
+
+    createAPIs() {
+      return {
+        login: createAPI(
+          async function(context, params: { identifier: string; password: string }) {
+            // Authenticate user
+            // Generate JWT token
+            // Return token to client
+          },
+          { allowAnonymous: true }
+        )
+      }
+    }
+  }
+}
+```
+
+**Key principles:**
+- **Middleware is optional**: Only use when needed for cross-cutting concerns
+- **Order matters**: Middleware executes in the order returned from createMiddlewares()
+- **Context injection**: Use `c.set()` to inject data into context for API handlers
+- **Non-blocking**: Always call `await next()` to continue the middleware chain
+- **Error handling**: Middleware can catch and handle errors before they reach API handlers
+
+**Common use cases:**
+1. **Authentication** (`integrations/auth/index.ts`): JWT verification, session management
+2. **Authorization**: Role-based access control, permission checks
+3. **Request validation**: Schema validation, sanitization
+4. **Logging**: Request/response logging, performance monitoring
+5. **Rate limiting**: Throttle requests per user/IP
+6. **CORS**: Handle cross-origin requests
+
 ## Example: Stripe Payment Integration
 
 ```typescript

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

@@ -553,6 +553,80 @@ git commit -m "feat: Task 1.2 - Complete functional requirements analysis"
 
 **External side-effects requiring third-party APIs must be identified separately.**
 
+### Special Case: Authentication Integration
+
+**⚠️ CRITICAL: Authentication for Basic Module**
+
+If the current module is "basic", authentication (login/registration) requirements must be handled as an integration named **"auth"**.
+
+**Authentication vs Business Logic:**
+1. **Authentication (Integration)**:
+   - User login with credentials
+   - User registration/signup
+   - Password reset/recovery
+   - OAuth/social login
+   - These are NOT part of business logic - treat as integration "auth"
+
+2. **User Management (Business Logic)**:
+   - Administrator creates user accounts
+   - Administrator updates user information
+   - Administrator deactivates users
+   - These ARE business data operations - design as regular interactions
+
+**Handling Authentication Requirements:**
+
+**Case 1: User explicitly described login/registration requirements**
+- Extract ALL authentication-related requirements into integration "auth"
+- Do NOT create interactions for login/registration in Task 1.5
+- Document the specific authentication flow in integration.json
+
+**Case 2: User did NOT mention login/registration**
+- For "basic" module, assume authentication is needed
+- Design a simple password-based authentication integration
+- Use default specification (see example below)
+
+**Default Password Authentication Integration:**
+```json
+{
+  "id": "INT_AUTH",
+  "name": "auth",
+  "type": "stateful-system",
+  "type_explanation": "Authentication system maintains session state and user credentials. Requires bidirectional communication for login, registration, and session management.",
+  "external_system": "Authentication Service",
+  "purpose": "Handle user authentication and registration for the system",
+  "related_requirements": ["User login", "User registration"],
+  "flow_description": "For registration: User provides username/email and password in current system. System sends registration request (username, password) to authentication service. Authentication service validates uniqueness, hashes password, creates auth record, and returns user credentials. Current system receives response and creates User entity with returned user ID. For login: User provides credentials in current system. System sends login request to authentication service. Authentication service validates credentials and returns session token. Current system stores session and grants access.",
+  "user_interactions": {
+    "in_current_system": [
+      "User enters username/email and password for registration",
+      "User enters credentials for login",
+      "User views login success/failure messages"
+    ],
+    "in_external_system": [
+      "Authentication service validates credential format",
+      "Authentication service checks username/email uniqueness",
+      "Authentication service hashes password securely",
+      "Authentication service generates session tokens"
+    ]
+  },
+  "current_system_data": [
+    {
+      "entity": "User",
+      "properties": ["id", "username", "email"],
+      "usage": "Created after successful registration using ID returned from authentication service. Read during login to fetch user profile."
+    }
+  ],
+  "notes": "This is a default password-based authentication. If user requirements specify OAuth, biometric, or other authentication methods, adjust accordingly."
+}
+```
+
+**Important Notes:**
+- Authentication integration should ALWAYS be named "auth" for consistency
+- Do NOT create "User" entity properties for password, passwordHash, or session tokens - these belong to the auth integration
+- User entity should only contain business-related properties (username, email, profile info)
+- In Task 1.4, do NOT create entities for authentication (no AuthSession, no Credentials entities)
+- In Task 1.5, do NOT create login/registration interactions - these are handled by the auth integration
+
 ### What is NOT an Integration
 
 **⚠️ CRITICAL: Intra-Project Module Access**
@@ -1280,6 +1354,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/agent/.claude/settings.local.json

@@ -73,7 +73,9 @@
       "Bash(else echo \"VOLC_ACCESS_KEY_ID is set\")",
       "Bash(fi:*)",
       "Bash(if [ -z \"$VOLC_SECRET_ACCESS_KEY\" ])",
-      "Bash(then echo \"VOLC_SECRET_ACCESS_KEY is empty or not set\")"
+      "Bash(then echo \"VOLC_SECRET_ACCESS_KEY is empty or not set\")",
+      "Bash(npm run)",
+      "Bash(chmod:*)"
     ],
     "deny": [],
     "ask": []

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.5",
   "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 仍然按照原文档的方式写。
-
-