@olane/o-protocol 0.8.2 → 0.8.4

package/CHANGELOG.md

@@ -3,6 +3,14 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+## <small>0.8.4 (2026-02-18)</small>
+
+- updated docs ([3cc950f](https://github.com/olane-labs/olane/commit/3cc950f))
+
+## <small>0.8.3 (2026-02-11)</small>
+
+**Note:** Version bump only for package @olane/o-protocol
+
 ## <small>0.8.2 (2026-02-10)</small>
 
 **Note:** Version bump only for package @olane/o-protocol

package/README.md

@@ -1,24 +1,289 @@
-# o-protocol
+# @olane/o-protocol
 
-A protocol designed for complex communication with anything
+Protocol specification and type definitions for the Olane network.
+
+## Installation
+
+```bash
+pnpm add @olane/o-protocol
+```
 
 ## Overview
-The o-network addressing system provides a hierarchical, federated approach to AI agent communication across distributed networks. This protocol enables AI agents to discover, access, and interact with tools and services through a simple yet powerful addressing scheme that scales from individual consumer networks to enterprise provider networks.
+
+The o-protocol defines the communication layer for AI agent interaction across distributed networks. It provides the type system, addressing scheme, JSON-RPC message format, method definitions, and routing interfaces that all Olane nodes use to discover, register, and communicate with each other.
 
 ## Key Features
-- Hierarchical P2P Network Structure - The primary use case is for resolving addresses within the o-network, a hierarchical federated network of p2p nodes [link to o-network README.md]
-- Universal Address Format - Example: o://network_name/node_group_name/node_name/node_tool/node_tool_method
-- Middleware-Enabled Routing - Each term within the address represents a p2p node that contains its own functionality that can be leveraged as middleware on its route to the destination leaf node
-- AI-Native Workflow Language - This simplistic address structure allows AI to create a common language for workflow structures which can be shared
-- Composable Plans - Combining multiple addresses is also possible resulting in Plans [link to plans README.md], which are also addressable and shareable too
-- Self-Improving Intelligence - As AI Agents think about how to accomplish a task within the context of an o-network, failure and success alike become context for how to achieve a better solution or resolve a previous failure
 
+- **Hierarchical P2P Network Structure** - Resolves addresses within the o-network, a hierarchical federated network of p2p nodes
+- **Universal Address Format** - `o://network_name/node_group_name/node_name/node_tool/node_tool_method`
+- **Middleware-Enabled Routing** - Each term within the address represents a p2p node that contains its own functionality that can be leveraged as middleware on its route to the destination leaf node
+- **JSON-RPC 2.0 Messaging** - Standard request/response protocol with typed error codes
+- **AI-Native Method Discovery** - Rich method definitions with parameters, examples, approval metadata, and performance hints for AI agent consumption
+
+## Usage
+
+### Defining Methods and Parameters
+
+Methods describe the capabilities a node exposes. Each method includes typed parameters, descriptions for AI discovery, and optional metadata for approval, performance, and error handling.
+
+```typescript
+import { oMethod, oParameter } from '@olane/o-protocol';
+
+const parameters: oParameter[] = [
+  {
+    name: 'customerId',
+    type: 'string',
+    description: 'Unique customer identifier (UUID)',
+    required: true,
+    exampleValues: ['cust_abc123'],
+  },
+  {
+    name: 'includeHistory',
+    type: 'boolean',
+    description: 'Include purchase history in the response',
+    required: false,
+    defaultValue: false,
+  },
+  {
+    name: 'status',
+    type: 'string',
+    description: 'Filter by account status',
+    required: false,
+    structure: { enum: ['active', 'inactive', 'suspended'] },
+  },
+];
+
+const methods: Record<string, oMethod> = {
+  get_customer: {
+    name: 'get_customer',
+    description: 'Retrieves customer information by ID.',
+    parameters,
+    dependencies: [],
+    requiresApproval: false,
+    examples: [
+      {
+        description: 'Fetch a customer by ID',
+        intent: 'Get customer details for cust_abc123',
+        params: { customerId: 'cust_abc123' },
+        expectedResult: { id: 'cust_abc123', name: 'Alice' },
+      },
+    ],
+    commonErrors: [
+      {
+        errorCode: 'CUSTOMER_NOT_FOUND',
+        message: 'No customer exists with the given ID',
+        causes: ['Invalid or expired customer ID'],
+        remediation: 'Verify the customer ID and try again',
+      },
+    ],
+    performance: {
+      estimatedDuration: 200,
+      cacheable: true,
+      cacheKey: ['customerId'],
+      idempotent: true,
+    },
+  },
+};
+```
+
+### Working with JSON-RPC Messages
+
+All Olane communication uses JSON-RPC 2.0. The protocol exports request, response, and error types along with standard error codes.
+
+```typescript
+import {
+  JSONRPC_VERSION,
+  JSONRPCRequest,
+  JSONRPCResponse,
+  JSONRPCError,
+  PARSE_ERROR,
+  INVALID_REQUEST,
+  METHOD_NOT_FOUND,
+  INVALID_PARAMS,
+  INTERNAL_ERROR,
+  oRequest,
+  oResponse,
+} from '@olane/o-protocol';
+
+// oRequest and oResponse are aliases for JSONRPCRequest and JSONRPCResponse
+const request: oRequest = {
+  jsonrpc: JSONRPC_VERSION,
+  id: 'req-1',
+  method: 'get_customer',
+  params: {
+    _connectionId: 'conn-1',
+    _requestMethod: 'get_customer',
+    customerId: 'cust_abc123',
+  },
+};
+```
+
+### Protocol Methods Enum
+
+Built-in protocol methods used for node lifecycle operations:
+
+```typescript
+import { oProtocolMethods } from '@olane/o-protocol';
+
+// oProtocolMethods.HANDSHAKE   = "handshake"
+// oProtocolMethods.REGISTER    = "register"
+// oProtocolMethods.ROUTE       = "route"
+// oProtocolMethods.INDEX_NETWORK = "index_network"
+// oProtocolMethods.INTENT      = "intent"
+// oProtocolMethods.INTENT_METHOD_CONFIGURATION = "intent_method_configuration"
+```
+
+## API Reference
+
+### oAddress
+
+Defines the transport and protocol for a node address.
+
+```typescript
+interface oAddress {
+  transports: string[];
+  protocol: string;
+}
+```
+
+### oMethod
+
+Describes a callable method on a node, including everything an AI agent needs for discovery and invocation.
+
+```typescript
+interface oMethod {
+  name: string;                        // Method identifier
+  description: string;                 // Human/AI-readable description
+  parameters: oParameter[];            // Input parameters
+  dependencies: oDependency[];         // External node dependencies
+  requiresApproval?: boolean;          // Whether human approval is needed
+  approvalMetadata?: oApprovalMetadata; // Risk level, category, auto-approve rules
+  examples?: oMethodExample[];         // Example invocations with expected results
+  commonErrors?: oCommonError[];       // Known failure modes and remediation
+  performance?: oPerformanceMetadata;  // Timing, caching, batching hints
+  successCriteria?: string;            // What constitutes a successful call
+  suggestedContext?: string[];         // Recommended context for the AI agent
+  similarMethods?: string[];           // Related methods for discovery
+}
+```
+
+### oParameter
+
+Defines a single input parameter for a method.
+
+```typescript
+interface oParameter {
+  name: string;                          // Parameter name
+  type: string;                          // Type: "string", "number", "boolean", "array", "object"
+  value?: any;                           // Pre-set value (if fixed)
+  description?: string;                  // Human/AI-readable description
+  required?: boolean;                    // Whether the parameter is required
+  options?: any[];                       // Allowed values (legacy, prefer structure.enum)
+  structure?: oParameterStructure;       // Nested structure, constraints, enums
+  schema?: any;                          // JSON Schema for complex validation
+  defaultValue?: any;                    // Default if not provided
+  exampleValues?: any[];                 // Example values for AI agents
+  validationRules?: string[];            // Validation rule descriptions
+}
+
+interface oParameterStructure {
+  objectProperties?: Record<string, oParameter>; // Properties for object types
+  arrayItems?: oParameter;                        // Item type for array types
+  enum?: any[];                                   // Allowed values
+  pattern?: string;                               // Regex pattern for strings
+  minimum?: number;                               // Minimum for numbers
+  maximum?: number;                               // Maximum for numbers
+  minLength?: number;                             // Min length for strings/arrays
+  maxLength?: number;                             // Max length for strings/arrays
+}
+```
+
+### oDependency
+
+Declares a dependency on another node in the network.
+
+```typescript
+interface oDependency {
+  address: string;            // o:// address of the dependency
+  version?: string;           // Required version
+  method?: string;            // Specific method required
+  parameters?: oParameter[];  // Parameters to pass
+}
+```
+
+### JSON-RPC Types
+
+| Type | Description |
+|------|-------------|
+| `JSONRPCRequest` | A request that expects a response (`jsonrpc`, `id`, `method`, `params`) |
+| `JSONRPCResponse` | A successful response (`jsonrpc`, `id`, `result`) |
+| `JSONRPCError` | An error response (`jsonrpc`, `id`, `error: { code, message, data? }`) |
+| `JSONRPCNotification` | A notification that does not expect a response |
+| `oRequest` | Alias for `JSONRPCRequest` |
+| `oResponse` | Alias for `JSONRPCResponse` |
+| `RequestId` | `string \| number` |
+
+### Standard Error Codes
+
+| Constant | Value | Meaning |
+|----------|-------|---------|
+| `PARSE_ERROR` | -32700 | Invalid JSON received |
+| `INVALID_REQUEST` | -32600 | JSON is not a valid request object |
+| `METHOD_NOT_FOUND` | -32601 | Method does not exist |
+| `INVALID_PARAMS` | -32602 | Invalid method parameters |
+| `INTERNAL_ERROR` | -32603 | Internal server error |
+
+### Approval Metadata
+
+Methods that perform sensitive operations can declare approval requirements:
+
+```typescript
+interface oApprovalMetadata {
+  riskLevel?: 'low' | 'medium' | 'high' | 'critical';
+  category?: 'read' | 'write' | 'destructive' | 'network' | 'system';
+  description?: string;
+  autoApproveConditions?: {
+    parameterConstraints?: Record<string, any>;
+    contextRequirements?: string[];
+    userRoles?: string[];
+  };
+  denialReasons?: string[];
+  alternativeMethods?: string[];
+}
+```
+
+### Performance Metadata
+
+Hints for AI agents and the runtime about method behavior:
+
+```typescript
+interface oPerformanceMetadata {
+  estimatedDuration?: number;    // Expected duration in ms
+  maxDuration?: number;          // Timeout threshold in ms
+  cacheable?: boolean;           // Whether results can be cached
+  cacheKey?: string[];           // Parameter names that form the cache key
+  idempotent?: boolean;          // Safe to retry
+  supportsBatching?: boolean;    // Can process multiple inputs
+  batchSizeLimit?: number;       // Max batch size
+  supportsStreaming?: boolean;    // Supports streaming responses
+}
+```
+
+### Registration and Routing
+
+Used internally by the node lifecycle for network registration and message routing:
+
+- **`oRegisterRequest`** - Request to register a node with `transports`, `peerId`, `address`, `protocols`, and optional `ttl`
+- **`oRouterRequestInterface`** - Request to route a message to an `address` with a `payload`
+- **`oHandshakeRequest` / `oHandshakeResponse`** - Initial capability exchange between nodes
 
-The addressing protocol transforms simple intents into executable plans, automatically caching successful workflows for future use and creating an evolving intelligence layer that improves over time.
+### Config
 
-## Action Complete & Deterministic Outcomes
+```typescript
+import { LATEST_PROTOCOL_VERSION } from '@olane/o-protocol';
+// LATEST_PROTOCOL_VERSION = '1.0.0'
+```
 
-### Hyper-Personalization
+## License
 
-## Why Build This?
-The current internet evolved around a world that lacked intelligence as a service, resulting in static workflows masqueraded as APIs or websites. With the advent of LLMs, the world is quickly adapting and in dire need of an infrastructure that can match this new dynamic / fluid system.
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@olane/o-protocol",
-  "version": "0.8.2",
+  "version": "0.8.4",
   "description": "oLane Protocol specification and protocol schema",
   "license": "MIT",
   "author": "oLane Inc. (https://olane.com)",
@@ -53,5 +53,5 @@
     "typescript": "^5.6.2",
     "typescript-json-schema": "^0.65.1"
   },
-  "gitHead": "9e35c874d849d051bcffe483fd2a8c2b3ecf68cc"
+  "gitHead": "b53623b1ad4365133911722f80d5597a72b65bf2"
 }