objectstack-ai · hotlong · Jan 30, 2026 · Jan 30, 2026 · Jan 30, 2026 · Jan 30, 2026
diff --git a/content/docs/references/ai/conversation.mdx b/content/docs/references/ai/conversation.mdx
@@ -77,6 +77,7 @@ const result = ConversationAnalyticsSchema.parse(data);
 | **toolCallId** | `string` | optional | Tool call ID this message responds to |
 | **name** | `string` | optional | Name of the function/user |
 | **tokens** | `object` | optional | Token usage for this message |
+| **cost** | `number` | optional | Cost for this message in USD |
 | **pinned** | `boolean` | optional | Prevent removal during pruning |
 | **importance** | `number` | optional | Importance score for pruning |
 | **embedding** | `number[]` | optional | Vector embedding for semantic search |
@@ -97,6 +98,8 @@ const result = ConversationAnalyticsSchema.parse(data);
 | **tokenBudget** | `object` | ✅ |  |
 | **messages** | `object[]` | optional |  |
 | **tokens** | `object` | optional |  |
+| **totalTokens** | `object` | optional | Total tokens across all messages |
+| **totalCost** | `number` | optional | Total cost for this session in USD |
 | **status** | `Enum<'active' \| 'paused' \| 'completed' \| 'archived'>` | optional |  |
 | **createdAt** | `string` | ✅ | ISO 8601 timestamp |
 | **updatedAt** | `string` | ✅ | ISO 8601 timestamp |

diff --git a/content/docs/references/ai/cost.mdx b/content/docs/references/ai/cost.mdx
@@ -12,15 +12,32 @@ description: Cost protocol schemas
 ## TypeScript Usage
 
 ```typescript
-import { BillingPeriodSchema, BudgetLimitSchema, BudgetStatusSchema, BudgetTypeSchema, CostAlertSchema, CostAlertTypeSchema, CostAnalyticsSchema, CostBreakdownDimensionSchema, CostBreakdownEntrySchema, CostEntrySchema, CostMetricTypeSchema, CostOptimizationRecommendationSchema, CostQueryFiltersSchema, CostReportSchema } from '@objectstack/spec/ai';
-import type { BillingPeriod, BudgetLimit, BudgetStatus, BudgetType, CostAlert, CostAlertType, CostAnalytics, CostBreakdownDimension, CostBreakdownEntry, CostEntry, CostMetricType, CostOptimizationRecommendation, CostQueryFilters, CostReport } from '@objectstack/spec/ai';
+import { AIOperationCostSchema, BillingPeriodSchema, BudgetLimitSchema, BudgetStatusSchema, BudgetTypeSchema, CostAlertSchema, CostAlertTypeSchema, CostAnalyticsSchema, CostBreakdownDimensionSchema, CostBreakdownEntrySchema, CostEntrySchema, CostMetricTypeSchema, CostOptimizationRecommendationSchema, CostQueryFiltersSchema, CostReportSchema, TokenUsageSchema } from '@objectstack/spec/ai';
+import type { AIOperationCost, BillingPeriod, BudgetLimit, BudgetStatus, BudgetType, CostAlert, CostAlertType, CostAnalytics, CostBreakdownDimension, CostBreakdownEntry, CostEntry, CostMetricType, CostOptimizationRecommendation, CostQueryFilters, CostReport, TokenUsage } from '@objectstack/spec/ai';
 
 // Validate data
-const result = BillingPeriodSchema.parse(data);
+const result = AIOperationCostSchema.parse(data);
 ```
 
 ---
 
+## AIOperationCost
+
+### Properties
+
+| Property | Type | Required | Description |
+| :--- | :--- | :--- | :--- |
+| **operationId** | `string` | ✅ |  |
+| **operationType** | `Enum<'conversation' \| 'orchestration' \| 'prediction' \| 'rag' \| 'nlq'>` | ✅ |  |
+| **agentName** | `string` | optional | Agent that performed the operation |
+| **modelId** | `string` | ✅ |  |
+| **tokens** | `object` | ✅ |  |
+| **cost** | `number` | ✅ | Cost in USD |
+| **timestamp** | `string` | ✅ |  |
+| **metadata** | `Record<string, any>` | optional |  |
+
+---
+
 ## BillingPeriod
 
 ### Allowed Values
@@ -316,3 +333,15 @@ const result = BillingPeriodSchema.parse(data);
 | **format** | `Enum<'summary' \| 'detailed' \| 'executive'>` | optional |  |
 | **currency** | `string` | optional |  |
 
+---
+
+## TokenUsage
+
+### Properties
+
+| Property | Type | Required | Description |
+| :--- | :--- | :--- | :--- |
+| **prompt** | `integer` | ✅ | Input tokens |
+| **completion** | `integer` | ✅ | Output tokens |
+| **total** | `integer` | ✅ | Total tokens |
+
diff --git a/content/docs/references/ai/nlq.mdx b/content/docs/references/ai/nlq.mdx
@@ -152,6 +152,8 @@ const result = EntitySchema.parse(data);
 | **totalCount** | `integer` | optional |  |
 | **executionTime** | `number` | optional | Execution time in milliseconds |
 | **needsClarification** | `boolean` | ✅ | Whether query needs clarification |
+| **tokens** | `object` | optional | Token usage for this query |
+| **cost** | `number` | optional | Cost for this query in USD |
 | **suggestions** | `string[]` | optional | Query refinement suggestions |
 
 ---

diff --git a/content/docs/references/ai/orchestration.mdx b/content/docs/references/ai/orchestration.mdx
@@ -69,6 +69,8 @@ const result = AIOrchestrationSchema.parse(data);
 | **tasksSucceeded** | `integer` | ✅ | Number of tasks succeeded |
 | **tasksFailed** | `integer` | ✅ | Number of tasks failed |
 | **taskResults** | `object[]` | optional |  |
+| **tokens** | `object` | optional | Total token usage for this execution |
+| **cost** | `number` | optional | Total cost for this execution in USD |
 | **error** | `string` | optional |  |
 | **startedAt** | `string` | ✅ | ISO timestamp |
 | **completedAt** | `string` | optional | ISO timestamp |

diff --git a/content/docs/references/ai/predictive.mdx b/content/docs/references/ai/predictive.mdx
@@ -131,6 +131,8 @@ const result = EvaluationMetricsSchema.parse(data);
 | **confidence** | `number` | optional | Confidence score (0-1) |
 | **probabilities** | `Record<string, number>` | optional | Class probabilities (for classification) |
 | **explanation** | `object` | optional |  |
+| **tokens** | `object` | optional | Token usage for this prediction (if AI-powered) |
+| **cost** | `number` | optional | Cost for this prediction in USD |
 | **metadata** | `object` | optional |  |
 
 ---

diff --git a/content/docs/references/ai/rag-pipeline.mdx b/content/docs/references/ai/rag-pipeline.mdx
@@ -157,7 +157,9 @@ const result = ChunkingStrategySchema.parse(data);
 | **query** | `string` | ✅ |  |
 | **results** | `object[]` | ✅ |  |
 | **context** | `string` | ✅ | Assembled context for LLM |
-| **tokensUsed** | `integer` | optional |  |
+| **tokens** | `object` | optional | Token usage for this query |
+| **cost** | `number` | optional | Cost for this query in USD |
+| **tokensUsed** | `integer` | optional | Deprecated: use tokens.total instead |
 | **retrievalTime** | `number` | optional | Retrieval time in milliseconds |
 
 ---

diff --git a/content/docs/references/ui/chart.mdx b/content/docs/references/ui/chart.mdx
@@ -0,0 +1,72 @@
+---
+title: Chart
+description: Chart protocol schemas
+---
+
+# Chart
+
+<Callout type="info">
+**Source:** `packages/spec/src/ui/chart.zod.ts`
+</Callout>
+
+## TypeScript Usage
+
+```typescript
+import { ChartConfigSchema, ChartTypeSchema } from '@objectstack/spec/ui';
+import type { ChartConfig, ChartType } from '@objectstack/spec/ui';
+
+// Validate data
+const result = ChartConfigSchema.parse(data);
+```
+
+---
+
+## ChartConfig
+
+### Properties
+
+| Property | Type | Required | Description |
+| :--- | :--- | :--- | :--- |
+| **type** | `Enum<'bar' \| 'horizontal-bar' \| 'column' \| 'grouped-bar' \| 'stacked-bar' \| 'line' \| 'area' \| 'stacked-area' \| 'step-line' \| 'pie' \| 'donut' \| 'funnel' \| 'scatter' \| 'bubble' \| 'treemap' \| 'sunburst' \| 'sankey' \| 'gauge' \| 'metric' \| 'kpi' \| 'choropleth' \| 'bubble-map' \| 'heatmap' \| 'radar' \| 'waterfall' \| 'box-plot' \| 'violin' \| 'table' \| 'pivot'>` | ✅ |  |
+| **title** | `string` | optional | Chart title |
+| **description** | `string` | optional | Chart description |
+| **showLegend** | `boolean` | optional | Display legend |
+| **showDataLabels** | `boolean` | optional | Display data labels on chart |
+| **colors** | `string[]` | optional | Custom color palette |
+
+---
+
+## ChartType
+
+### Allowed Values
+
+* `bar`
+* `horizontal-bar`
+* `column`
+* `grouped-bar`
+* `stacked-bar`
+* `line`
+* `area`
+* `stacked-area`
+* `step-line`
+* `pie`
+* `donut`
+* `funnel`
+* `scatter`
+* `bubble`
+* `treemap`
+* `sunburst`
+* `sankey`
+* `gauge`
+* `metric`
+* `kpi`
+* `choropleth`
+* `bubble-map`
+* `heatmap`
+* `radar`
+* `waterfall`
+* `box-plot`
+* `violin`
+* `table`
+* `pivot`
+
diff --git a/content/docs/references/ui/dashboard.mdx b/content/docs/references/ui/dashboard.mdx
@@ -12,38 +12,15 @@ description: Dashboard protocol schemas
 ## TypeScript Usage
 
 ```typescript
-import { ChartTypeSchema, DashboardSchema, DashboardWidgetSchema } from '@objectstack/spec/ui';
-import type { ChartType, Dashboard, DashboardWidget } from '@objectstack/spec/ui';
+import { DashboardSchema, DashboardWidgetSchema } from '@objectstack/spec/ui';
+import type { Dashboard, DashboardWidget } from '@objectstack/spec/ui';
 
 // Validate data
-const result = ChartTypeSchema.parse(data);
+const result = DashboardSchema.parse(data);
 ```
 
 ---
 
-## ChartType
-
-### Allowed Values
-
-* `metric`
-* `bar`
-* `line`
-* `pie`
-* `donut`
-* `gauge`
-* `funnel`
-* `radar`
-* `scatter`
-* `heatmap`
-* `pivot`
-* `table`
-* `list`
-* `text`
-* `image`
-* `frame`
-
----
-
 ## Dashboard
 
 ### Properties
@@ -64,7 +41,8 @@ const result = ChartTypeSchema.parse(data);
 | Property | Type | Required | Description |
 | :--- | :--- | :--- | :--- |
 | **title** | `string` | optional | Widget title |
-| **type** | `Enum<'metric' \| 'bar' \| 'line' \| 'pie' \| 'donut' \| 'gauge' \| 'funnel' \| 'radar' \| 'scatter' \| 'heatmap' \| 'pivot' \| 'table' \| 'list' \| 'text' \| 'image' \| 'frame'>` | optional | Visualization type |
+| **type** | `Enum<'bar' \| 'horizontal-bar' \| 'column' \| 'grouped-bar' \| 'stacked-bar' \| 'line' \| 'area' \| 'stacked-area' \| 'step-line' \| 'pie' \| 'donut' \| 'funnel' \| 'scatter' \| 'bubble' \| 'treemap' \| 'sunburst' \| 'sankey' \| 'gauge' \| 'metric' \| 'kpi' \| 'choropleth' \| 'bubble-map' \| 'heatmap' \| 'radar' \| 'waterfall' \| 'box-plot' \| 'violin' \| 'table' \| 'pivot'>` | optional | Visualization type |
+| **chartConfig** | `object` | optional | Chart visualization configuration |
 | **object** | `string` | optional | Data source object name |
 | **filter** | `any` | optional | Data filter criteria |
 | **categoryField** | `string` | optional | Field for grouping (X-Axis) |

diff --git a/content/docs/references/ui/index.mdx b/content/docs/references/ui/index.mdx
@@ -10,6 +10,7 @@ This section contains all protocol schemas for the ui layer of ObjectStack.
 <Cards>
   <Card href="./action" title="Action" description="Source: packages/spec/src/ui/action.zod.ts" />
   <Card href="./app" title="App" description="Source: packages/spec/src/ui/app.zod.ts" />
+  <Card href="./chart" title="Chart" description="Source: packages/spec/src/ui/chart.zod.ts" />
   <Card href="./component" title="Component" description="Source: packages/spec/src/ui/component.zod.ts" />
   <Card href="./dashboard" title="Dashboard" description="Source: packages/spec/src/ui/dashboard.zod.ts" />
   <Card href="./page" title="Page" description="Source: packages/spec/src/ui/page.zod.ts" />

diff --git a/content/docs/references/ui/meta.json b/content/docs/references/ui/meta.json
@@ -3,6 +3,7 @@
   "pages": [
     "action",
     "app",
+    "chart",
     "component",
     "dashboard",
     "page",

diff --git a/content/docs/references/ui/report.mdx b/content/docs/references/ui/report.mdx
@@ -46,11 +46,15 @@ const result = ReportSchema.parse(data);
 
 | Property | Type | Required | Description |
 | :--- | :--- | :--- | :--- |
-| **type** | `Enum<'bar' \| 'column' \| 'line' \| 'pie' \| 'donut' \| 'scatter' \| 'funnel'>` | ✅ | Chart type |
-| **title** | `string` | optional |  |
-| **showLegend** | `boolean` | optional |  |
+| **type** | `Enum<'bar' \| 'horizontal-bar' \| 'column' \| 'grouped-bar' \| 'stacked-bar' \| 'line' \| 'area' \| 'stacked-area' \| 'step-line' \| 'pie' \| 'donut' \| 'funnel' \| 'scatter' \| 'bubble' \| 'treemap' \| 'sunburst' \| 'sankey' \| 'gauge' \| 'metric' \| 'kpi' \| 'choropleth' \| 'bubble-map' \| 'heatmap' \| 'radar' \| 'waterfall' \| 'box-plot' \| 'violin' \| 'table' \| 'pivot'>` | ✅ |  |
+| **title** | `string` | optional | Chart title |
+| **description** | `string` | optional | Chart description |
+| **showLegend** | `boolean` | optional | Display legend |
+| **showDataLabels** | `boolean` | optional | Display data labels on chart |
+| **colors** | `string[]` | optional | Custom color palette |
 | **xAxis** | `string` | ✅ | Grouping field for X-Axis |
 | **yAxis** | `string` | ✅ | Summary field for Y-Axis |
+| **groupBy** | `string` | optional | Additional grouping field |
 
 ---
 

diff --git a/packages/spec/json-schema/ai/AIOperationCost.json b/packages/spec/json-schema/ai/AIOperationCost.json
@@ -0,0 +1,79 @@
+{
+  "$ref": "#/definitions/AIOperationCost",
+  "definitions": {
+    "AIOperationCost": {
+      "type": "object",
+      "properties": {
+        "operationId": {
+          "type": "string"
+        },
+        "operationType": {
+          "type": "string",
+          "enum": [
+            "conversation",
+            "orchestration",
+            "prediction",
+            "rag",
+            "nlq"
+          ]
+        },
+        "agentName": {
+          "type": "string",
+          "description": "Agent that performed the operation"
+        },
+        "modelId": {
+          "type": "string"
+        },
+        "tokens": {
+          "type": "object",
+          "properties": {
+            "prompt": {
+              "type": "integer",
+              "minimum": 0,
+              "description": "Input tokens"
+            },
+            "completion": {
+              "type": "integer",
+              "minimum": 0,
+              "description": "Output tokens"
+            },
+            "total": {
+              "type": "integer",
+              "minimum": 0,
+              "description": "Total tokens"
+            }
+          },
+          "required": [
+            "prompt",
+            "completion",
+            "total"
+          ],
+          "additionalProperties": false
+        },
+        "cost": {
+          "type": "number",
+          "minimum": 0,
+          "description": "Cost in USD"
+        },
+        "timestamp": {
+          "type": "string",
+          "format": "date-time"
+        },
+        "metadata": {
+          "type": "object",
+          "additionalProperties": {}
+        }
+      },
+      "required": [
+        "operationId",
+        "operationType",
+        "modelId",
+        "tokens",
+        "cost",
+        "timestamp"
+      ],
+      "additionalProperties": false
+    }
+  },
+  "$schema": "http://json-schema.org/draft-07/schema#"
+}
diff --git a/packages/spec/json-schema/ai/AIOrchestrationExecutionResult.json b/packages/spec/json-schema/ai/AIOrchestrationExecutionResult.json
@@ -76,6 +76,38 @@
             "additionalProperties": false
           }
         },
+        "tokens": {
+          "type": "object",
+          "properties": {
+            "prompt": {
+              "type": "integer",
+              "minimum": 0,
+              "description": "Input tokens"
+            },
+            "completion": {
+              "type": "integer",
+              "minimum": 0,
+              "description": "Output tokens"
+            },
+            "total": {
+              "type": "integer",
+              "minimum": 0,
+              "description": "Total tokens"
+            }
+          },
+          "required": [
+            "prompt",
+            "completion",
+            "total"
+          ],
+          "additionalProperties": false,
+          "description": "Total token usage for this execution"
+        },
+        "cost": {
+          "type": "number",
+          "minimum": 0,
+          "description": "Total cost for this execution in USD"
+        },
         "error": {
           "type": "string"
         },