Merge pull request #389 from objectstack-ai/copilot/architectural-review-objectstack-protocol

Author: hotlong

IMPLEMENTATION_SUMMARY.md

@@ -0,0 +1,342 @@
+---
+title: Agent Action
+description: Agent Action protocol schemas
+---
+
+# Agent Action
+
+<Callout type="info">
+**Source:** `packages/spec/src/ai/agent-action.zod.ts`
+</Callout>
+
+## TypeScript Usage
+
+```typescript
+import { AgentActionSchema, AgentActionResultSchema, AgentActionSequenceSchema, AgentActionSequenceResultSchema, ComponentActionParamsSchema, ComponentActionTypeSchema, DataActionParamsSchema, DataActionTypeSchema, FormActionParamsSchema, FormActionTypeSchema, IntentActionMappingSchema, NavigationActionParamsSchema, NavigationActionTypeSchema, UIActionTypeSchema, ViewActionParamsSchema, ViewActionTypeSchema, WorkflowActionParamsSchema, WorkflowActionTypeSchema } from '@objectstack/spec/ai';
+import type { AgentAction, AgentActionResult, AgentActionSequence, AgentActionSequenceResult, ComponentActionParams, ComponentActionType, DataActionParams, DataActionType, FormActionParams, FormActionType, IntentActionMapping, NavigationActionParams, NavigationActionType, UIActionType, ViewActionParams, ViewActionType, WorkflowActionParams, WorkflowActionType } from '@objectstack/spec/ai';
+
+// Validate data
+const result = AgentActionSchema.parse(data);
+```
+
+---
+
+## AgentAction
+
+### Properties
+
+| Property | Type | Required | Description |
+| :--- | :--- | :--- | :--- |
+| **id** | `string` | optional | Unique action ID |
+| **type** | `Enum<'navigate_to_object_list' \| 'navigate_to_object_form' \| 'navigate_to_record_detail' \| 'navigate_to_dashboard' \| 'navigate_to_report' \| 'navigate_to_app' \| 'navigate_back' \| 'navigate_home' \| 'open_tab' \| 'close_tab' \| 'change_view_mode' \| 'apply_filter' \| 'clear_filter' \| 'apply_sort' \| 'change_grouping' \| 'show_columns' \| 'expand_record' \| 'collapse_record' \| 'refresh_view' \| 'export_data' \| 'create_record' \| 'update_record' \| 'delete_record' \| 'fill_field' \| 'clear_field' \| 'submit_form' \| 'cancel_form' \| 'validate_form' \| 'save_draft' \| 'select_record' \| 'deselect_record' \| 'select_all' \| 'deselect_all' \| 'bulk_update' \| 'bulk_delete' \| 'bulk_export' \| 'trigger_flow' \| 'trigger_approval' \| 'trigger_webhook' \| 'run_report' \| 'send_email' \| 'send_notification' \| 'schedule_task' \| 'open_modal' \| 'close_modal' \| 'open_sidebar' \| 'close_sidebar' \| 'show_notification' \| 'hide_notification' \| 'open_dropdown' \| 'close_dropdown' \| 'toggle_section'>` | ✅ | Type of UI action to perform |
+| **params** | `object \| object \| object \| object \| object \| object` | ✅ | Action-specific parameters |
+| **requireConfirmation** | `boolean` | optional | Require user confirmation before executing |
+| **confirmationMessage** | `string` | optional | Message to show in confirmation dialog |
+| **successMessage** | `string` | optional | Message to show on success |
+| **onError** | `Enum<'retry' \| 'skip' \| 'abort'>` | optional | Error handling strategy |
+| **metadata** | `object` | optional |  |
+
+---
+
+## AgentActionResult
+
+### Properties
+
+| Property | Type | Required | Description |
+| :--- | :--- | :--- | :--- |
+| **actionId** | `string` | ✅ | ID of the executed action |
+| **status** | `Enum<'success' \| 'error' \| 'cancelled' \| 'pending'>` | ✅ | Execution status |
+| **data** | `any` | optional | Action result data |
+| **error** | `object` | optional | Error details if status is "error" |
+| **metadata** | `object` | optional |  |
+
+---
+
+## AgentActionSequence
+
+### Properties
+
+| Property | Type | Required | Description |
+| :--- | :--- | :--- | :--- |
+| **id** | `string` | optional | Unique sequence ID |
+| **actions** | `object[]` | ✅ | Ordered list of actions |
+| **mode** | `Enum<'sequential' \| 'parallel'>` | optional | Execution mode |
+| **stopOnError** | `boolean` | optional | Stop sequence on first error |
+| **atomic** | `boolean` | optional | Rollback all changes if any action fails |
+| **metadata** | `object` | optional |  |
+
+---
+
+## AgentActionSequenceResult
+
+### Properties
+
+| Property | Type | Required | Description |
+| :--- | :--- | :--- | :--- |
+| **sequenceId** | `string` | ✅ | ID of the executed sequence |
+| **status** | `Enum<'success' \| 'partial_success' \| 'error' \| 'cancelled'>` | ✅ | Overall execution status |
+| **results** | `object[]` | ✅ | Results for each action |
+| **summary** | `object` | ✅ |  |
+| **metadata** | `object` | optional |  |
+
+---
+
+## ComponentActionParams
+
+### Properties
+
+| Property | Type | Required | Description |
+| :--- | :--- | :--- | :--- |
+| **componentId** | `string` | optional | Component ID |
+| **modalConfig** | `object` | optional |  |
+| **notificationConfig** | `object` | optional |  |
+| **sidebarConfig** | `object` | optional |  |
+
+---
+
+## ComponentActionType
+
+### Allowed Values
+
+* `open_modal`
+* `close_modal`
+* `open_sidebar`
+* `close_sidebar`
+* `show_notification`
+* `hide_notification`
+* `open_dropdown`
+* `close_dropdown`
+* `toggle_section`
+
+---
+
+## DataActionParams
+
+### Properties
+
+| Property | Type | Required | Description |
+| :--- | :--- | :--- | :--- |
+| **recordIds** | `string[]` | optional | Record IDs to select/operate on |
+| **filters** | `Record<string, any>` | optional | Filter for bulk operations |
+| **updateData** | `Record<string, any>` | optional | Data for bulk update |
+| **exportFormat** | `Enum<'csv' \| 'xlsx' \| 'pdf' \| 'json'>` | optional |  |
+
+---
+
+## DataActionType
+
+### Allowed Values
+
+* `select_record`
+* `deselect_record`
+* `select_all`
+* `deselect_all`
+* `bulk_update`
+* `bulk_delete`
+* `bulk_export`
+
+---
+
+## FormActionParams
+
+### Properties
+
+| Property | Type | Required | Description |
+| :--- | :--- | :--- | :--- |
+| **object** | `string` | optional | Object name |
+| **recordId** | `string` | optional | Record ID (for edit/delete) |
+| **fieldValues** | `Record<string, any>` | optional | Field name-value pairs |
+| **fieldName** | `string` | optional | Specific field to fill/clear |
+| **fieldValue** | `any` | optional | Value to set |
+| **validateOnly** | `boolean` | optional | Validate without saving |
+
+---
+
+## FormActionType
+
+### Allowed Values
+
+* `create_record`
+* `update_record`
+* `delete_record`
+* `fill_field`
+* `clear_field`
+* `submit_form`
+* `cancel_form`
+* `validate_form`
+* `save_draft`
+
+---
+
+## IntentActionMapping
+
+### Properties
+
+| Property | Type | Required | Description |
+| :--- | :--- | :--- | :--- |
+| **intent** | `string` | ✅ | Intent pattern (e.g., "open_new_record_form") |
+| **examples** | `string[]` | optional | Example user queries |
+| **actionTemplate** | `object` | ✅ | Action to execute |
+| **paramExtraction** | `Record<string, object>` | optional | Rules for extracting parameters from user input |
+| **minConfidence** | `number` | optional | Minimum confidence to execute |
+
+---
+
+## NavigationActionParams
+
+### Properties
+
+| Property | Type | Required | Description |
+| :--- | :--- | :--- | :--- |
+| **object** | `string` | optional | Object name (for object-specific navigation) |
+| **recordId** | `string` | optional | Record ID (for detail page) |
+| **viewType** | `Enum<'list' \| 'form' \| 'detail' \| 'kanban' \| 'calendar' \| 'gantt'>` | optional |  |
+| **dashboardId** | `string` | optional | Dashboard ID |
+| **reportId** | `string` | optional | Report ID |
+| **appName** | `string` | optional | App name |
+| **mode** | `Enum<'new' \| 'edit' \| 'view'>` | optional | Form mode |
+| **openInNewTab** | `boolean` | optional | Open in new tab |
+
+---
+
+## NavigationActionType
+
+### Allowed Values
+
+* `navigate_to_object_list`
+* `navigate_to_object_form`
+* `navigate_to_record_detail`
+* `navigate_to_dashboard`
+* `navigate_to_report`
+* `navigate_to_app`
+* `navigate_back`
+* `navigate_home`
+* `open_tab`
+* `close_tab`
+
+---
+
+## UIActionType
+
+### Allowed Values
+
+* `navigate_to_object_list`
+* `navigate_to_object_form`
+* `navigate_to_record_detail`
+* `navigate_to_dashboard`
+* `navigate_to_report`
+* `navigate_to_app`
+* `navigate_back`
+* `navigate_home`
+* `open_tab`
+* `close_tab`
+* `change_view_mode`
+* `apply_filter`
+* `clear_filter`
+* `apply_sort`
+* `change_grouping`
+* `show_columns`
+* `expand_record`
+* `collapse_record`
+* `refresh_view`
+* `export_data`
+* `create_record`
+* `update_record`
+* `delete_record`
+* `fill_field`
+* `clear_field`
+* `submit_form`
+* `cancel_form`
+* `validate_form`
+* `save_draft`
+* `select_record`
+* `deselect_record`
+* `select_all`
+* `deselect_all`
+* `bulk_update`
+* `bulk_delete`
+* `bulk_export`
+* `trigger_flow`
+* `trigger_approval`
+* `trigger_webhook`
+* `run_report`
+* `send_email`
+* `send_notification`
+* `schedule_task`
+* `open_modal`
+* `close_modal`
+* `open_sidebar`
+* `close_sidebar`
+* `show_notification`
+* `hide_notification`
+* `open_dropdown`
+* `close_dropdown`
+* `toggle_section`
+
+---
+
+## ViewActionParams
+
+### Properties
+
+| Property | Type | Required | Description |
+| :--- | :--- | :--- | :--- |
+| **viewMode** | `Enum<'list' \| 'kanban' \| 'calendar' \| 'gantt' \| 'pivot'>` | optional |  |
+| **filters** | `Record<string, any>` | optional | Filter conditions |
+| **sort** | `object[]` | optional |  |
+| **groupBy** | `string` | optional | Field to group by |
+| **columns** | `string[]` | optional | Columns to show/hide |
+| **recordId** | `string` | optional | Record to expand/collapse |
+| **exportFormat** | `Enum<'csv' \| 'xlsx' \| 'pdf' \| 'json'>` | optional |  |
+
+---
+
+## ViewActionType
+
+### Allowed Values
+
+* `change_view_mode`
+* `apply_filter`
+* `clear_filter`
+* `apply_sort`
+* `change_grouping`
+* `show_columns`
+* `expand_record`
+* `collapse_record`
+* `refresh_view`
+* `export_data`
+
+---
+
+## WorkflowActionParams
+
+### Properties
+
+| Property | Type | Required | Description |
+| :--- | :--- | :--- | :--- |
+| **flowName** | `string` | optional | Flow/workflow name |
+| **approvalProcessName** | `string` | optional | Approval process name |
+| **webhookUrl** | `string` | optional | Webhook URL |
+| **reportName** | `string` | optional | Report name |
+| **emailTemplate** | `string` | optional | Email template |
+| **recipients** | `string[]` | optional | Email recipients |
+| **subject** | `string` | optional | Email subject |
+| **message** | `string` | optional | Notification/email message |
+| **taskData** | `Record<string, any>` | optional | Task creation data |
+| **scheduleTime** | `string` | optional | Schedule time (ISO 8601) |
+| **contextData** | `Record<string, any>` | optional | Additional context data |
+
+---
+
+## WorkflowActionType
+
+### Allowed Values
+
+* `trigger_flow`
+* `trigger_approval`
+* `trigger_webhook`
+* `run_report`
+* `send_email`
+* `send_notification`
+* `schedule_task`
+

content/docs/references/ai/agent-action.mdx

@@ -9,6 +9,7 @@ This section contains all protocol schemas for the ai layer of ObjectStack.
 
 <Cards>
   <Card href="./agent" title="Agent" description="Source: packages/spec/src/ai/agent.zod.ts" />
+  <Card href="./agent-action" title="Agent Action" description="Source: packages/spec/src/ai/agent-action.zod.ts" />
   <Card href="./conversation" title="Conversation" description="Source: packages/spec/src/ai/conversation.zod.ts" />
   <Card href="./cost" title="Cost" description="Source: packages/spec/src/ai/cost.zod.ts" />
   <Card href="./model-registry" title="Model Registry" description="Source: packages/spec/src/ai/model-registry.zod.ts" />

content/docs/references/ai/index.mdx

@@ -2,6 +2,7 @@
   "title": "AI Protocol",
   "pages": [
     "agent",
+    "agent-action",
     "conversation",
     "cost",
     "model-registry",

content/docs/references/ai/meta.json

@@ -16,6 +16,7 @@ This section contains all protocol schemas for the api layer of ObjectStack.
   <Card href="./errors" title="Errors" description="Source: packages/spec/src/api/errors.zod.ts" />
   <Card href="./graphql" title="Graphql" description="Source: packages/spec/src/api/graphql.zod.ts" />
   <Card href="./odata" title="Odata" description="Source: packages/spec/src/api/odata.zod.ts" />
+  <Card href="./protocol" title="Protocol" description="Source: packages/spec/src/api/protocol.zod.ts" />
   <Card href="./realtime" title="Realtime" description="Source: packages/spec/src/api/realtime.zod.ts" />
   <Card href="./router" title="Router" description="Source: packages/spec/src/api/router.zod.ts" />
   <Card href="./view-storage" title="View Storage" description="Source: packages/spec/src/api/view-storage.zod.ts" />

content/docs/references/api/index.mdx

@@ -9,6 +9,7 @@
     "errors",
     "graphql",
     "odata",
+    "protocol",
     "realtime",
     "router",
     "view-storage",