@agent-watch/protocol 0.1.0

package/README.md

@@ -0,0 +1,322 @@
+# @agentwatch/protocol
+
+The single authoritative definition of every message type in the AgentWatch protocol. TypeScript components import types and validators at compile time and runtime. Mobile apps use this repository as their reference for implementing equivalent Swift and Kotlin types.
+
+## Installation
+
+```bash
+npm install @agentwatch/protocol
+```
+
+## Usage
+
+### Importing Types
+
+```typescript
+import { 
+  Session, 
+  AgentAction, 
+  ApprovalRequest,
+  ApprovalResponse,
+  SubscriptionStatus,
+  validate 
+} from '@agentwatch/protocol';
+
+// Use types for type safety
+const session: Session = {
+  id: 'sess_123',
+  ide: 'vscode',
+  cwd: '/home/user/project',
+  startedAt: '2026-03-21T10:00:00Z',
+  status: 'active',
+};
+```
+
+### Validating Data
+
+```typescript
+import { validate } from '@agentwatch/protocol';
+
+// Validate incoming data
+const result = validate.session(unknownData);
+
+if (result.success) {
+  // Data is valid and typed
+  console.log(`Session ${result.data.id} started at ${result.data.startedAt}`);
+} else {
+  // Validation failed with detailed errors
+  result.errors.forEach(err => {
+    console.error(`${err.field}: ${err.message}`);
+  });
+}
+```
+
+## Core Type Definitions
+
+### Session
+
+A single agent conversation — tracks ID, IDE, working directory, timestamps, and status.
+
+**Fields:**
+- `id` (string, required): Unique session identifier
+- `ide` (string, required): IDE name (e.g., "vscode", "cursor", "windsurf")
+- `cwd` (string, required): Current working directory at session start
+- `startedAt` (string, required): ISO 8601 timestamp when session started
+- `endedAt` (string, optional): ISO 8601 timestamp when session ended
+- `status` (string, required): Current status — `"active" | "completed" | "failed" | "cancelled"`
+- `pairingId` (string, optional): Pairing ID if session is paired to a device
+
+**Used by:** All components
+
+### AgentAction
+
+A single agent tool call — tracks action details, tier, and outcome.
+
+**Fields:**
+- `id` (string, required): Unique action identifier
+- `sessionId` (string, required): Session this action belongs to
+- `toolName` (string, required): Tool name (e.g., "read_file", "run_in_terminal")
+- `input` (object, required): Tool input parameters as JSON object
+- `summary` (string, required): Human-readable summary of the action
+- `tier` (string, required): Action tier — `"read" | "write" | "run"`
+- `timestamp` (string, required): ISO 8601 timestamp when action was requested
+- `outcome` (string, optional): Action outcome — `"allowed" | "denied" | "auto_approved"`
+- `autoApprovalRecord` (object, optional): Auto-approval details if outcome is `auto_approved`
+  - `reason` (string, required): Reason for auto-approval — `"limit_reached"`
+  - `limitType` (string, required): Type of limit reached — `"daily" | "monthly"`
+  - `resetDate` (string, required): ISO 8601 timestamp when limit resets
+
+**Used by:** Daemon, hook, relay
+
+### ApprovalRequest
+
+Pending decision requiring user approval.
+
+**Fields:**
+- `approvalId` (string, required): Unique approval request identifier
+- `sessionId` (string, required): Session this approval belongs to
+- `action` (AgentAction, required): The action requiring approval
+- `precedingActions` (AgentAction[], required): Previous actions in this session for context
+- `timeout` (string, required): ISO 8601 timestamp when request expires
+
+**Used by:** Daemon, relay, phone apps
+
+### ApprovalResponse
+
+User decision on an approval request.
+
+**Fields:**
+- `approvalId` (string, required): Approval request ID this response is for
+- `sessionId` (string, required): Session ID
+- `decision` (string, required): User's decision — `"allow" | "deny"`
+- `signature` (string, required): HMAC signature for authenticity verification
+- `timestamp` (string, required): ISO 8601 timestamp when decision was made
+
+**Used by:** Phone apps, daemon
+
+### PushPayload
+
+Relay envelope for encrypted messages sent via FCM/APNs.
+
+**Fields:**
+- `type` (string, required): Payload type — `"approval_request" | "session_start" | "session_end" | "subscription_event"`
+- `sessionId` (string, optional): Session ID (if applicable)
+- `pairingId` (string, required): Pairing ID for routing
+- `encryptedBlob` (string, required): Encrypted message blob (base64 encoded)
+
+**Used by:** Daemon, relay
+
+### DeviceRegistration
+
+Phone app registration data for push notifications.
+
+**Fields:**
+- `deviceToken` (string, required): FCM or APNs device token
+- `platform` (string, required): Platform type — `"ios" | "android"`
+- `sessionId` (string, optional): Current session ID (if registering during session)
+- `pairingId` (string, required): Pairing ID for device linkage
+
+**Used by:** Phone apps, relay
+
+### HookInput
+
+IDE stdin payload sent to the hook script.
+
+**Fields:**
+- `eventName` (string, required): Event being reported — `"tool_call" | "session_start" | "session_end"`
+- `sessionId` (string, required): Session ID
+- `cwd` (string, required): Current working directory
+- `toolName` (string, optional): Tool name (for tool_call events)
+- `toolInput` (object, optional): Tool input parameters (for tool_call events)
+
+**Used by:** Hook script
+
+### HookOutput
+
+Hook response sent back to the IDE.
+
+**Fields:**
+- `decision` (string, required): Decision for the hook event — `"allow" | "deny"`
+- `reason` (string, optional): Optional reason for denial
+
+**Used by:** Hook script
+
+## Subscription Type Definitions (v2)
+
+### SubscriptionStatus
+
+User's current subscription and entitlement status.
+
+**Fields:**
+- `plan` (string, required): Current subscription plan — `"free" | "pro" | "enterprise"`
+- `approvalCount` (number, required): Current approval count in period
+- `approvalLimit` (number | null, required): Approval limit for current plan (null = unlimited)
+- `resetDate` (string, required): ISO 8601 timestamp when approval count resets
+- `deviceCount` (number, required): Number of paired devices
+- `featureFlags` (string[], required): Enabled feature flags — `"unlimited_approvals" | "priority_support" | "custom_branding"`
+
+**Used by:** Relay GET /status, daemon, phone apps
+
+### EntitlementRequest
+
+Request to check if a user is entitled to perform an action.
+
+**Fields:**
+- `pairingId` (string, required): Pairing ID making the request
+- `accountId` (string, required): Account ID for the user
+- `actionType` (string, required): Action type being checked
+
+**Used by:** Relay to accounts service
+
+### EntitlementResponse
+
+Result of an entitlement check.
+
+**Fields:**
+- `decision` (string, required): Whether action is allowed — `"allowed" | "denied" | "soft_limit_warning"`
+- `errorCode` (string, optional): Error code if denied — `"limit_exceeded" | "plan_downgraded" | "account_suspended" | "invalid_pairing"`
+- `count` (number, required): Current count in period
+- `limit` (number | null, required): Limit for current plan (null = unlimited)
+- `resetDate` (string, required): ISO 8601 timestamp when count resets
+
+**Used by:** Accounts service to relay
+
+### SubscriptionEvent
+
+FCM message for subscription limit events.
+
+**Fields:**
+- `eventType` (string, required): Event type — `"limit_reached" | "limit_warning" | "plan_upgraded" | "plan_downgraded"`
+- `limitType` (string, optional): Limit type for limit events — `"daily" | "monthly"`
+- `count` (number, optional): Current count for limit events
+- `limit` (number, optional): Limit value for limit events
+- `resetDate` (string, optional): ISO 8601 timestamp when count resets
+- `newPlan` (string, optional): New plan for upgrade/downgrade events — `"free" | "pro" | "enterprise"`
+
+**Used by:** Relay to phone apps
+
+### AutoApprovalRecord
+
+Embedded in AgentAction when outcome is `auto_approved`. Determines whether the session timeline shows the amber auto-approval indicator.
+
+**Fields:**
+- `reason` (string, required): Reason for auto-approval — `"limit_reached"`
+- `limitType` (string, required): Type of limit that was reached — `"daily" | "monthly"`
+- `resetDate` (string, required): ISO 8601 timestamp when the limit resets
+
+**Used by:** Daemon, phone apps
+
+## Mobile Implementation Reference
+
+This section documents all protocol types in plain language for iOS (Swift) and Android (Kotlin) developers.
+
+### Implementing Types in Swift
+
+Use `Codable` structs with snake_case to camelCase mapping:
+
+```swift
+struct Session: Codable {
+    let id: String
+    let ide: String
+    let cwd: String
+    let startedAt: String
+    let endedAt: String?
+    let status: SessionStatus
+    let pairingId: String?
+    
+    enum CodingKeys: String, CodingKey {
+        case id, ide, cwd, status
+        case startedAt = "startedAt"
+        case endedAt = "endedAt"
+        case pairingId = "pairingId"
+    }
+}
+
+enum SessionStatus: String, Codable {
+    case active, completed, failed, cancelled
+}
+```
+
+### Implementing Types in Kotlin
+
+Use `data class` with `@SerializedName` annotations:
+
+```kotlin
+data class Session(
+    @SerializedName("id") val id: String,
+    @SerializedName("ide") val ide: String,
+    @SerializedName("cwd") val cwd: String,
+    @SerializedName("startedAt") val startedAt: String,
+    @SerializedName("endedAt") val endedAt: String?,
+    @SerializedName("status") val status: SessionStatus,
+    @SerializedName("pairingId") val pairingId: String?
+)
+
+enum class SessionStatus {
+    @SerializedName("active") ACTIVE,
+    @SerializedName("completed") COMPLETED,
+    @SerializedName("failed") FAILED,
+    @SerializedName("cancelled") CANCELLED
+}
+```
+
+### Important Implementation Notes
+
+1. **All timestamps are ISO 8601 strings** — Parse them using appropriate date formatters:
+   - Swift: `ISO8601DateFormatter()`
+   - Kotlin: `SimpleDateFormat("yyyy-MM-dd'T'HH:mm:ss'Z'", Locale.US)`
+
+2. **Enum values are exact strings** — Never use free-form strings. All plan names, error codes, event types, and resolution types are enums.
+
+3. **AutoApprovalRecord is critical** — When an `AgentAction` has `outcome = "auto_approved"` and includes an `autoApprovalRecord`, the mobile UI must show the amber auto-approval indicator on the timeline.
+
+4. **Nested objects** — `ApprovalRequest` contains an `action` field (type `AgentAction`) and `precedingActions` array (`AgentAction[]`). Implement these as nested types.
+
+5. **Optional vs Required** — Fields marked optional in the TypeScript types should be nullable in Swift/Kotlin. All other fields are required.
+
+## Validation
+
+All types have strict JSON schema validators with:
+- `additionalProperties: false` — Rejects unexpected fields
+- Explicit `maxLength` on all string fields
+- Required fields explicitly listed
+- Enum constraints on all categorical values
+
+## Versioning
+
+This package follows semantic versioning:
+
+| Version Bump | Meaning | Coordination Required |
+|--------------|---------|----------------------|
+| **Major** | Breaking change — field removed, type changed, required field added | Coordinated release: protocol + desktop + relay + mobile apps |
+| **Minor** | New optional fields added — backwards compatible | Desktop and relay update independently. Mobile adds new types. |
+| **Patch** | Documentation or validator fixes only — no API change | Any component updates independently |
+
+## Contributing
+
+See [CHANGELOG.md](./CHANGELOG.md) for version history. Every release includes date, change description, affected components, and migration guides for major versions.
+
+## License
+
+MIT
+

package/dist/index.d.ts

@@ -0,0 +1,15 @@
+/**
+ * @agentwatch/protocol
+ *
+ * Single authoritative definition of every message type in the AgentWatch protocol.
+ * TypeScript components import types and validators at compile time and runtime.
+ */
+export * from './types/session';
+export * from './types/action';
+export * from './types/approval';
+export * from './types/push';
+export * from './types/registration';
+export * from './types/hook';
+export * from './types/subscription';
+export { validate, ValidationResult } from './validators';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,cAAc,iBAAiB,CAAC;AAChC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,kBAAkB,CAAC;AACjC,cAAc,cAAc,CAAC;AAC7B,cAAc,sBAAsB,CAAC;AACrC,cAAc,cAAc,CAAC;AAC7B,cAAc,sBAAsB,CAAC;AAGrC,OAAO,EAAE,QAAQ,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC"}

package/dist/index.js

@@ -0,0 +1,35 @@
+"use strict";
+/**
+ * @agentwatch/protocol
+ *
+ * Single authoritative definition of every message type in the AgentWatch protocol.
+ * TypeScript components import types and validators at compile time and runtime.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validate = void 0;
+// Export all types
+__exportStar(require("./types/session"), exports);
+__exportStar(require("./types/action"), exports);
+__exportStar(require("./types/approval"), exports);
+__exportStar(require("./types/push"), exports);
+__exportStar(require("./types/registration"), exports);
+__exportStar(require("./types/hook"), exports);
+__exportStar(require("./types/subscription"), exports);
+// Export validators
+var validators_1 = require("./validators");
+Object.defineProperty(exports, "validate", { enumerable: true, get: function () { return validators_1.validate; } });
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAAA;;;;;GAKG;;;;;;;;;;;;;;;;;AAEH,mBAAmB;AACnB,kDAAgC;AAChC,iDAA+B;AAC/B,mDAAiC;AACjC,+CAA6B;AAC7B,uDAAqC;AACrC,+CAA6B;AAC7B,uDAAqC;AAErC,oBAAoB;AACpB,2CAA0D;AAAjD,sGAAA,QAAQ,OAAA"}

package/dist/schemas/action.schema.json

@@ -0,0 +1,71 @@
+{
+    "$schema": "http://json-schema.org/draft-07/schema#",
+    "type": "object",
+    "title": "AgentAction",
+    "description": "A single agent tool call",
+    "additionalProperties": false,
+    "required": ["id", "sessionId", "toolName", "input", "summary", "tier", "timestamp"],
+    "properties": {
+        "id": {
+            "type": "string",
+            "description": "Unique action identifier",
+            "maxLength": 255
+        },
+        "sessionId": {
+            "type": "string",
+            "description": "Session this action belongs to",
+            "maxLength": 255
+        },
+        "toolName": {
+            "type": "string",
+            "description": "Tool name",
+            "maxLength": 255
+        },
+        "input": {
+            "type": "object",
+            "description": "Tool input parameters"
+        },
+        "summary": {
+            "type": "string",
+            "description": "Human-readable summary",
+            "maxLength": 2048
+        },
+        "tier": {
+            "type": "string",
+            "description": "Action tier",
+            "enum": ["read", "write", "run"]
+        },
+        "timestamp": {
+            "type": "string",
+            "description": "ISO 8601 timestamp when action was requested",
+            "format": "date-time",
+            "maxLength": 64
+        },
+        "outcome": {
+            "type": "string",
+            "description": "Action outcome",
+            "enum": ["allowed", "denied", "auto_approved"]
+        },
+        "autoApprovalRecord": {
+            "type": "object",
+            "description": "Auto-approval details",
+            "additionalProperties": false,
+            "required": ["reason", "limitType", "resetDate"],
+            "properties": {
+                "reason": {
+                    "type": "string",
+                    "enum": ["limit_reached"]
+                },
+                "limitType": {
+                    "type": "string",
+                    "enum": ["daily", "monthly"]
+                },
+                "resetDate": {
+                    "type": "string",
+                    "format": "date-time",
+                    "maxLength": 64
+                }
+            }
+        }
+    }
+}

package/dist/schemas/approval-request.schema.json

@@ -0,0 +1,36 @@
+{
+    "$schema": "http://json-schema.org/draft-07/schema#",
+    "type": "object",
+    "title": "ApprovalRequest",
+    "description": "Pending decision requiring user approval",
+    "additionalProperties": false,
+    "required": ["approvalId", "sessionId", "action", "precedingActions", "timeout"],
+    "properties": {
+        "approvalId": {
+            "type": "string",
+            "description": "Unique approval request identifier",
+            "maxLength": 255
+        },
+        "sessionId": {
+            "type": "string",
+            "description": "Session this approval belongs to",
+            "maxLength": 255
+        },
+        "action": {
+            "$ref": "./action.schema.json"
+        },
+        "precedingActions": {
+            "type": "array",
+            "description": "Previous actions in this session",
+            "items": {
+                "$ref": "./action.schema.json"
+            }
+        },
+        "timeout": {
+            "type": "string",
+            "description": "ISO 8601 timestamp when request expires",
+            "format": "date-time",
+            "maxLength": 64
+        }
+    }
+}

package/dist/schemas/approval-response.schema.json

@@ -0,0 +1,36 @@
+{
+    "$schema": "http://json-schema.org/draft-07/schema#",
+    "type": "object",
+    "title": "ApprovalResponse",
+    "description": "User decision on approval request",
+    "additionalProperties": false,
+    "required": ["approvalId", "sessionId", "decision", "signature", "timestamp"],
+    "properties": {
+        "approvalId": {
+            "type": "string",
+            "description": "Approval request ID",
+            "maxLength": 255
+        },
+        "sessionId": {
+            "type": "string",
+            "description": "Session ID",
+            "maxLength": 255
+        },
+        "decision": {
+            "type": "string",
+            "description": "User's decision",
+            "enum": ["allow", "deny"]
+        },
+        "signature": {
+            "type": "string",
+            "description": "HMAC signature for authenticity",
+            "maxLength": 512
+        },
+        "timestamp": {
+            "type": "string",
+            "description": "ISO 8601 timestamp when decision was made",
+            "format": "date-time",
+            "maxLength": 64
+        }
+    }
+}

package/dist/schemas/entitlement-request.schema.json

@@ -0,0 +1,25 @@
+{
+    "$schema": "http://json-schema.org/draft-07/schema#",
+    "type": "object",
+    "title": "EntitlementRequest",
+    "description": "Request to check user entitlement",
+    "additionalProperties": false,
+    "required": ["pairingId", "accountId", "actionType"],
+    "properties": {
+        "pairingId": {
+            "type": "string",
+            "description": "Pairing ID making the request",
+            "maxLength": 255
+        },
+        "accountId": {
+            "type": "string",
+            "description": "Account ID for the user",
+            "maxLength": 255
+        },
+        "actionType": {
+            "type": "string",
+            "description": "Action type being checked",
+            "maxLength": 255
+        }
+    }
+}

package/dist/schemas/entitlement-response.schema.json

@@ -0,0 +1,38 @@
+{
+    "$schema": "http://json-schema.org/draft-07/schema#",
+    "type": "object",
+    "title": "EntitlementResponse",
+    "description": "Entitlement check result",
+    "additionalProperties": false,
+    "required": ["decision", "count", "limit", "resetDate"],
+    "properties": {
+        "decision": {
+            "type": "string",
+            "description": "Whether action is allowed",
+            "enum": ["allowed", "denied", "soft_limit_warning"]
+        },
+        "errorCode": {
+            "type": "string",
+            "description": "Error code if denied",
+            "enum": ["limit_exceeded", "plan_downgraded", "account_suspended", "invalid_pairing"]
+        },
+        "count": {
+            "type": "integer",
+            "description": "Current count in period",
+            "minimum": 0
+        },
+        "limit": {
+            "description": "Limit for current plan (null = unlimited)",
+            "oneOf": [
+                { "type": "integer", "minimum": 0 },
+                { "type": "null" }
+            ]
+        },
+        "resetDate": {
+            "type": "string",
+            "description": "ISO 8601 timestamp when count resets",
+            "format": "date-time",
+            "maxLength": 64
+        }
+    }
+}

package/dist/schemas/hook-input.schema.json

@@ -0,0 +1,34 @@
+{
+    "$schema": "http://json-schema.org/draft-07/schema#",
+    "type": "object",
+    "title": "HookInput",
+    "description": "IDE stdin payload for hook script",
+    "additionalProperties": false,
+    "required": ["eventName", "sessionId", "cwd"],
+    "properties": {
+        "eventName": {
+            "type": "string",
+            "description": "Event being reported",
+            "enum": ["tool_call", "session_start", "session_end"]
+        },
+        "sessionId": {
+            "type": "string",
+            "description": "Session ID",
+            "maxLength": 255
+        },
+        "cwd": {
+            "type": "string",
+            "description": "Current working directory",
+            "maxLength": 4096
+        },
+        "toolName": {
+            "type": "string",
+            "description": "Tool name for tool_call events",
+            "maxLength": 255
+        },
+        "toolInput": {
+            "type": "object",
+            "description": "Tool input parameters for tool_call events"
+        }
+    }
+}

package/dist/schemas/hook-output.schema.json

@@ -0,0 +1,20 @@
+{
+    "$schema": "http://json-schema.org/draft-07/schema#",
+    "type": "object",
+    "title": "HookOutput",
+    "description": "Hook response to IDE",
+    "additionalProperties": false,
+    "required": ["decision"],
+    "properties": {
+        "decision": {
+            "type": "string",
+            "description": "Decision for the hook event",
+            "enum": ["allow", "deny"]
+        },
+        "reason": {
+            "type": "string",
+            "description": "Optional reason for denial",
+            "maxLength": 2048
+        }
+    }
+}

package/dist/schemas/push.schema.json

@@ -0,0 +1,30 @@
+{
+    "$schema": "http://json-schema.org/draft-07/schema#",
+    "type": "object",
+    "title": "PushPayload",
+    "description": "Relay envelope for encrypted messages",
+    "additionalProperties": false,
+    "required": ["type", "pairingId", "encryptedBlob"],
+    "properties": {
+        "type": {
+            "type": "string",
+            "description": "Type of payload",
+            "enum": ["approval_request", "session_start", "session_end", "subscription_event"]
+        },
+        "sessionId": {
+            "type": "string",
+            "description": "Session ID if applicable",
+            "maxLength": 255
+        },
+        "pairingId": {
+            "type": "string",
+            "description": "Pairing ID for routing",
+            "maxLength": 255
+        },
+        "encryptedBlob": {
+            "type": "string",
+            "description": "Encrypted message blob (base64 encoded)",
+            "maxLength": 1048576
+        }
+    }
+}