@objectstack/spec 0.3.2 → 0.4.1

package/README.md

@@ -22,25 +22,35 @@ pnpm install @objectstack/spec
 
 ## 📦 Architecture
 
-The specification is divided into three protocols:
+The specification is organized into five namespaces mapping to the three-layer architecture:
 
-### 1. Data Protocol (`src/data`)
-*Core Business Logic & Data Modeling*
+### 1. Data Protocol (`src/data`) - *ObjectQL*
+*Business Kernel & Data Logic*
 *   `Object`, `Field`, `Validation`
-*   `Query` (AST), `Mapping` (ETL)
+*   `Query` (AST), `Driver` (Interface), `Datasource`
 *   `Permission`, `Sharing`, `Flow`
 
-### 2. UI Protocol (`src/ui`)
+### 2. AI Protocol (`src/ai`) - *ObjectQL*
+*Intelligence & Orchestration*
+*   `Agent` (Orchestration), `RAG` (Retrieval)
+*   `Model` (Registry), `Prompt`
+
+### 3. UI Protocol (`src/ui`) - *ObjectUI*
 *Presentation & Interaction*
 *   `App`, `Page`, `View` (Grid/Kanban)
 *   `Dashboard` (Widgets), `Report`
 *   `Action` (Triggers)
 
-### 3. System Protocol (`src/system`)
-*Runtime Configuration & Security*
-*   `Manifest` (Config), `Datasource`
-*   `Role` (Hierarchy), `Identity` (Auth)
-*   `Webhook` (Integration), `Policy` (Compliance)
+### 4. System Protocol (`src/system`) - *ObjectOS*
+*Runtime Infrastructure & Security*
+*   `Manifest` (Config), `Identity` (Auth)
+*   `Role` (RBAC), `Tenant` (Isolation)
+*   `Events` (Bus), `Plugin` (Lifecycle)
+
+### 5. API Protocol (`src/api`) - *ObjectOS*
+*Connectivity & Contracts*
+*   `Contract` (DTOs), `Endpoint` (Gateway)
+*   `Discovery` (Metadata), `Realtime` (Socket)
 
 ## 📚 Usage
 
@@ -48,6 +58,18 @@ The specification is divided into three protocols:
 
 **Important:** This package does NOT export types at the root level to prevent naming conflicts. You must use one of the following import styles:
 
+### 🤖 AI-Ready Context
+
+This package includes a `prompts/` directory containing system instructions and architectural context. This is useful for:
+1.  **AI Agents**: Creating agents that understand ObjectStack.
+2.  **IDE Context**: Adding `node_modules/@objectstack/spec/prompts/*.md` to your Cursor/Copilot context.
+3.  **LLM Auto-Discovery**: The `llms.txt` file in the root provides a knowledge base for autonomous agents.
+
+```typescript
+import context from '@objectstack/spec/prompts/architecture.md?raw'; // If using Vite/bundler
+// Or just read the file from disk
+```
+
 #### 1. Namespace Imports from Root
 
 Import protocol namespaces from the package root:

package/dist/ai/agent.zod.d.ts

@@ -9,14 +9,14 @@ export declare const AIModelConfigSchema: z.ZodObject<{
     maxTokens: z.ZodOptional<z.ZodNumber>;
     topP: z.ZodOptional<z.ZodNumber>;
 }, "strip", z.ZodTypeAny, {
-    provider: "openai" | "azure_openai" | "anthropic" | "local";
+    provider: "local" | "openai" | "azure_openai" | "anthropic";
     model: string;
     temperature: number;
     maxTokens?: number | undefined;
     topP?: number | undefined;
 }, {
     model: string;
-    provider?: "openai" | "azure_openai" | "anthropic" | "local" | undefined;
+    provider?: "local" | "openai" | "azure_openai" | "anthropic" | undefined;
     temperature?: number | undefined;
     maxTokens?: number | undefined;
     topP?: number | undefined;
@@ -30,11 +30,11 @@ export declare const AIToolSchema: z.ZodObject<{
     name: z.ZodString;
     description: z.ZodOptional<z.ZodString>;
 }, "strip", z.ZodTypeAny, {
-    type: "action" | "flow" | "query" | "vector_search";
+    type: "flow" | "query" | "action" | "vector_search";
     name: string;
     description?: string | undefined;
 }, {
-    type: "action" | "flow" | "query" | "vector_search";
+    type: "flow" | "query" | "action" | "vector_search";
     name: string;
     description?: string | undefined;
 }>;
@@ -71,14 +71,14 @@ export declare const AgentSchema: z.ZodObject<{
         maxTokens: z.ZodOptional<z.ZodNumber>;
         topP: z.ZodOptional<z.ZodNumber>;
     }, "strip", z.ZodTypeAny, {
-        provider: "openai" | "azure_openai" | "anthropic" | "local";
+        provider: "local" | "openai" | "azure_openai" | "anthropic";
         model: string;
         temperature: number;
         maxTokens?: number | undefined;
         topP?: number | undefined;
     }, {
         model: string;
-        provider?: "openai" | "azure_openai" | "anthropic" | "local" | undefined;
+        provider?: "local" | "openai" | "azure_openai" | "anthropic" | undefined;
         temperature?: number | undefined;
         maxTokens?: number | undefined;
         topP?: number | undefined;
@@ -89,11 +89,11 @@ export declare const AgentSchema: z.ZodObject<{
         name: z.ZodString;
         description: z.ZodOptional<z.ZodString>;
     }, "strip", z.ZodTypeAny, {
-        type: "action" | "flow" | "query" | "vector_search";
+        type: "flow" | "query" | "action" | "vector_search";
         name: string;
         description?: string | undefined;
     }, {
-        type: "action" | "flow" | "query" | "vector_search";
+        type: "flow" | "query" | "action" | "vector_search";
         name: string;
         description?: string | undefined;
     }>, "many">>;
@@ -118,14 +118,14 @@ export declare const AgentSchema: z.ZodObject<{
     instructions: string;
     avatar?: string | undefined;
     model?: {
-        provider: "openai" | "azure_openai" | "anthropic" | "local";
+        provider: "local" | "openai" | "azure_openai" | "anthropic";
         model: string;
         temperature: number;
         maxTokens?: number | undefined;
         topP?: number | undefined;
     } | undefined;
     tools?: {
-        type: "action" | "flow" | "query" | "vector_search";
+        type: "flow" | "query" | "action" | "vector_search";
         name: string;
         description?: string | undefined;
     }[] | undefined;
@@ -143,13 +143,13 @@ export declare const AgentSchema: z.ZodObject<{
     active?: boolean | undefined;
     model?: {
         model: string;
-        provider?: "openai" | "azure_openai" | "anthropic" | "local" | undefined;
+        provider?: "local" | "openai" | "azure_openai" | "anthropic" | undefined;
         temperature?: number | undefined;
         maxTokens?: number | undefined;
         topP?: number | undefined;
     } | undefined;
     tools?: {
-        type: "action" | "flow" | "query" | "vector_search";
+        type: "flow" | "query" | "action" | "vector_search";
         name: string;
         description?: string | undefined;
     }[] | undefined;

package/dist/ai/conversation.zod.d.ts

@@ -24,19 +24,19 @@ export declare const MessageContentSchema: z.ZodObject<{
     mimeType: z.ZodOptional<z.ZodString>;
     metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
 }, "strip", z.ZodTypeAny, {
-    type: "text" | "image" | "file" | "code" | "structured";
+    type: "code" | "text" | "image" | "file" | "structured";
     text?: string | undefined;
     metadata?: Record<string, any> | undefined;
+    mimeType?: string | undefined;
     imageUrl?: string | undefined;
     fileUrl?: string | undefined;
-    mimeType?: string | undefined;
 }, {
+    type?: "code" | "text" | "image" | "file" | "structured" | undefined;
     text?: string | undefined;
-    type?: "text" | "image" | "file" | "code" | "structured" | undefined;
     metadata?: Record<string, any> | undefined;
+    mimeType?: string | undefined;
     imageUrl?: string | undefined;
     fileUrl?: string | undefined;
-    mimeType?: string | undefined;
 }>;
 /**
  * Function Call
@@ -107,19 +107,19 @@ export declare const ConversationMessageSchema: z.ZodObject<{
         mimeType: z.ZodOptional<z.ZodString>;
         metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
     }, "strip", z.ZodTypeAny, {
-        type: "text" | "image" | "file" | "code" | "structured";
+        type: "code" | "text" | "image" | "file" | "structured";
         text?: string | undefined;
         metadata?: Record<string, any> | undefined;
+        mimeType?: string | undefined;
         imageUrl?: string | undefined;
         fileUrl?: string | undefined;
-        mimeType?: string | undefined;
     }, {
+        type?: "code" | "text" | "image" | "file" | "structured" | undefined;
         text?: string | undefined;
-        type?: "text" | "image" | "file" | "code" | "structured" | undefined;
         metadata?: Record<string, any> | undefined;
+        mimeType?: string | undefined;
         imageUrl?: string | undefined;
         fileUrl?: string | undefined;
-        mimeType?: string | undefined;
     }>, "many">]>;
     /** Function/Tool Calls */
     functionCall: z.ZodOptional<z.ZodObject<{
@@ -176,13 +176,13 @@ export declare const ConversationMessageSchema: z.ZodObject<{
         completion: z.ZodOptional<z.ZodNumber>;
         total: z.ZodOptional<z.ZodNumber>;
     }, "strip", z.ZodTypeAny, {
+        total?: number | undefined;
         prompt?: number | undefined;
         completion?: number | undefined;
-        total?: number | undefined;
     }, {
+        total?: number | undefined;
         prompt?: number | undefined;
         completion?: number | undefined;
-        total?: number | undefined;
     }>>;
     /** Context Management */
     pinned: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
@@ -192,23 +192,23 @@ export declare const ConversationMessageSchema: z.ZodObject<{
     metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
 }, "strip", z.ZodTypeAny, {
     id: string;
-    role: "function" | "system" | "user" | "assistant" | "tool";
+    role: "function" | "user" | "system" | "assistant" | "tool";
     timestamp: string;
     content: string | {
-        type: "text" | "image" | "file" | "code" | "structured";
+        type: "code" | "text" | "image" | "file" | "structured";
         text?: string | undefined;
         metadata?: Record<string, any> | undefined;
+        mimeType?: string | undefined;
         imageUrl?: string | undefined;
         fileUrl?: string | undefined;
-        mimeType?: string | undefined;
     }[];
     pinned: boolean;
     name?: string | undefined;
     metadata?: Record<string, any> | undefined;
     tokens?: {
+        total?: number | undefined;
         prompt?: number | undefined;
         completion?: number | undefined;
-        total?: number | undefined;
     } | undefined;
     embedding?: number[] | undefined;
     importance?: number | undefined;
@@ -229,22 +229,22 @@ export declare const ConversationMessageSchema: z.ZodObject<{
     toolCallId?: string | undefined;
 }, {
     id: string;
-    role: "function" | "system" | "user" | "assistant" | "tool";
+    role: "function" | "user" | "system" | "assistant" | "tool";
     timestamp: string;
     content: string | {
+        type?: "code" | "text" | "image" | "file" | "structured" | undefined;
         text?: string | undefined;
-        type?: "text" | "image" | "file" | "code" | "structured" | undefined;
         metadata?: Record<string, any> | undefined;
+        mimeType?: string | undefined;
         imageUrl?: string | undefined;
         fileUrl?: string | undefined;
-        mimeType?: string | undefined;
     }[];
     name?: string | undefined;
     metadata?: Record<string, any> | undefined;
     tokens?: {
+        total?: number | undefined;
         prompt?: number | undefined;
         completion?: number | undefined;
-        total?: number | undefined;
     } | undefined;
     embedding?: number[] | undefined;
     importance?: number | undefined;
@@ -500,19 +500,19 @@ export declare const ConversationSessionSchema: z.ZodObject<{
             mimeType: z.ZodOptional<z.ZodString>;
             metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
         }, "strip", z.ZodTypeAny, {
-            type: "text" | "image" | "file" | "code" | "structured";
+            type: "code" | "text" | "image" | "file" | "structured";
             text?: string | undefined;
             metadata?: Record<string, any> | undefined;
+            mimeType?: string | undefined;
             imageUrl?: string | undefined;
             fileUrl?: string | undefined;
-            mimeType?: string | undefined;
         }, {
+            type?: "code" | "text" | "image" | "file" | "structured" | undefined;
             text?: string | undefined;
-            type?: "text" | "image" | "file" | "code" | "structured" | undefined;
             metadata?: Record<string, any> | undefined;
+            mimeType?: string | undefined;
             imageUrl?: string | undefined;
             fileUrl?: string | undefined;
-            mimeType?: string | undefined;
         }>, "many">]>;
         /** Function/Tool Calls */
         functionCall: z.ZodOptional<z.ZodObject<{
@@ -569,13 +569,13 @@ export declare const ConversationSessionSchema: z.ZodObject<{
             completion: z.ZodOptional<z.ZodNumber>;
             total: z.ZodOptional<z.ZodNumber>;
         }, "strip", z.ZodTypeAny, {
+            total?: number | undefined;
             prompt?: number | undefined;
             completion?: number | undefined;
-            total?: number | undefined;
         }, {
+            total?: number | undefined;
             prompt?: number | undefined;
             completion?: number | undefined;
-            total?: number | undefined;
         }>>;
         /** Context Management */
         pinned: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
@@ -585,23 +585,23 @@ export declare const ConversationSessionSchema: z.ZodObject<{
         metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
     }, "strip", z.ZodTypeAny, {
         id: string;
-        role: "function" | "system" | "user" | "assistant" | "tool";
+        role: "function" | "user" | "system" | "assistant" | "tool";
         timestamp: string;
         content: string | {
-            type: "text" | "image" | "file" | "code" | "structured";
+            type: "code" | "text" | "image" | "file" | "structured";
             text?: string | undefined;
             metadata?: Record<string, any> | undefined;
+            mimeType?: string | undefined;
             imageUrl?: string | undefined;
             fileUrl?: string | undefined;
-            mimeType?: string | undefined;
         }[];
         pinned: boolean;
         name?: string | undefined;
         metadata?: Record<string, any> | undefined;
         tokens?: {
+            total?: number | undefined;
             prompt?: number | undefined;
             completion?: number | undefined;
-            total?: number | undefined;
         } | undefined;
         embedding?: number[] | undefined;
         importance?: number | undefined;
@@ -622,22 +622,22 @@ export declare const ConversationSessionSchema: z.ZodObject<{
         toolCallId?: string | undefined;
     }, {
         id: string;
-        role: "function" | "system" | "user" | "assistant" | "tool";
+        role: "function" | "user" | "system" | "assistant" | "tool";
         timestamp: string;
         content: string | {
+            type?: "code" | "text" | "image" | "file" | "structured" | undefined;
             text?: string | undefined;
-            type?: "text" | "image" | "file" | "code" | "structured" | undefined;
             metadata?: Record<string, any> | undefined;
+            mimeType?: string | undefined;
             imageUrl?: string | undefined;
             fileUrl?: string | undefined;
-            mimeType?: string | undefined;
         }[];
         name?: string | undefined;
         metadata?: Record<string, any> | undefined;
         tokens?: {
+            total?: number | undefined;
             prompt?: number | undefined;
             completion?: number | undefined;
-            total?: number | undefined;
         } | undefined;
         embedding?: number[] | undefined;
         importance?: number | undefined;
@@ -706,6 +706,7 @@ export declare const ConversationSessionSchema: z.ZodObject<{
     metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
 }, "strip", z.ZodTypeAny, {
     status: "active" | "archived" | "paused" | "completed";
+    id: string;
     context: {
         sessionId: string;
         object?: string | undefined;
@@ -716,28 +717,25 @@ export declare const ConversationSessionSchema: z.ZodObject<{
         agentId?: string | undefined;
         systemMessage?: string | undefined;
     };
-    id: string;
-    createdAt: string;
-    updatedAt: string;
     messages: {
         id: string;
-        role: "function" | "system" | "user" | "assistant" | "tool";
+        role: "function" | "user" | "system" | "assistant" | "tool";
         timestamp: string;
         content: string | {
-            type: "text" | "image" | "file" | "code" | "structured";
+            type: "code" | "text" | "image" | "file" | "structured";
             text?: string | undefined;
             metadata?: Record<string, any> | undefined;
+            mimeType?: string | undefined;
             imageUrl?: string | undefined;
             fileUrl?: string | undefined;
-            mimeType?: string | undefined;
         }[];
         pinned: boolean;
         name?: string | undefined;
         metadata?: Record<string, any> | undefined;
         tokens?: {
+            total?: number | undefined;
             prompt?: number | undefined;
             completion?: number | undefined;
-            total?: number | undefined;
         } | undefined;
         embedding?: number[] | undefined;
         importance?: number | undefined;
@@ -757,6 +755,8 @@ export declare const ConversationSessionSchema: z.ZodObject<{
         }[] | undefined;
         toolCallId?: string | undefined;
     }[];
+    createdAt: string;
+    updatedAt: string;
     tokenBudget: {
         strategy: "summary" | "semantic" | "importance" | "fifo" | "sliding_window";
         maxTokens: number;
@@ -772,11 +772,11 @@ export declare const ConversationSessionSchema: z.ZodObject<{
         summarizationThreshold?: number | undefined;
         summaryModel?: string | undefined;
     };
+    tags?: string[] | undefined;
     name?: string | undefined;
-    expiresAt?: string | undefined;
-    metadata?: Record<string, any> | undefined;
     modelId?: string | undefined;
-    tags?: string[] | undefined;
+    metadata?: Record<string, any> | undefined;
+    expiresAt?: string | undefined;
     tokens?: {
         promptTokens: number;
         completionTokens: number;
@@ -790,6 +790,7 @@ export declare const ConversationSessionSchema: z.ZodObject<{
         summarizedMessageCount: number;
     } | undefined;
 }, {
+    id: string;
     context: {
         sessionId: string;
         object?: string | undefined;
@@ -800,7 +801,6 @@ export declare const ConversationSessionSchema: z.ZodObject<{
         agentId?: string | undefined;
         systemMessage?: string | undefined;
     };
-    id: string;
     createdAt: string;
     updatedAt: string;
     tokenBudget: {
@@ -819,28 +819,28 @@ export declare const ConversationSessionSchema: z.ZodObject<{
         warnThreshold?: number | undefined;
     };
     status?: "active" | "archived" | "paused" | "completed" | undefined;
+    tags?: string[] | undefined;
     name?: string | undefined;
-    expiresAt?: string | undefined;
-    metadata?: Record<string, any> | undefined;
     modelId?: string | undefined;
+    metadata?: Record<string, any> | undefined;
     messages?: {
         id: string;
-        role: "function" | "system" | "user" | "assistant" | "tool";
+        role: "function" | "user" | "system" | "assistant" | "tool";
         timestamp: string;
         content: string | {
+            type?: "code" | "text" | "image" | "file" | "structured" | undefined;
             text?: string | undefined;
-            type?: "text" | "image" | "file" | "code" | "structured" | undefined;
             metadata?: Record<string, any> | undefined;
+            mimeType?: string | undefined;
             imageUrl?: string | undefined;
             fileUrl?: string | undefined;
-            mimeType?: string | undefined;
         }[];
         name?: string | undefined;
         metadata?: Record<string, any> | undefined;
         tokens?: {
+            total?: number | undefined;
             prompt?: number | undefined;
             completion?: number | undefined;
-            total?: number | undefined;
         } | undefined;
         embedding?: number[] | undefined;
         importance?: number | undefined;
@@ -861,7 +861,7 @@ export declare const ConversationSessionSchema: z.ZodObject<{
         toolCallId?: string | undefined;
         pinned?: boolean | undefined;
     }[] | undefined;
-    tags?: string[] | undefined;
+    expiresAt?: string | undefined;
     tokens?: {
         budgetLimit: number;
         budgetRemaining: number;
@@ -940,12 +940,12 @@ export declare const MessagePruningEventSchema: z.ZodObject<{
         tokens: z.ZodNumber;
         importance: z.ZodOptional<z.ZodNumber>;
     }, "strip", z.ZodTypeAny, {
-        role: "function" | "system" | "user" | "assistant" | "tool";
+        role: "function" | "user" | "system" | "assistant" | "tool";
         tokens: number;
         messageId: string;
         importance?: number | undefined;
     }, {
-        role: "function" | "system" | "user" | "assistant" | "tool";
+        role: "function" | "user" | "system" | "assistant" | "tool";
         tokens: number;
         messageId: string;
         importance?: number | undefined;
@@ -961,7 +961,7 @@ export declare const MessagePruningEventSchema: z.ZodObject<{
     timestamp: string;
     reason: string;
     prunedMessages: {
-        role: "function" | "system" | "user" | "assistant" | "tool";
+        role: "function" | "user" | "system" | "assistant" | "tool";
         tokens: number;
         messageId: string;
         importance?: number | undefined;
@@ -975,7 +975,7 @@ export declare const MessagePruningEventSchema: z.ZodObject<{
     timestamp: string;
     reason: string;
     prunedMessages: {
-        role: "function" | "system" | "user" | "assistant" | "tool";
+        role: "function" | "user" | "system" | "assistant" | "tool";
         tokens: number;
         messageId: string;
         importance?: number | undefined;