@agent-watch/protocol

@agent-watch/protocol

Shared TypeScript type definitions and JSON schema validators for all AgentWatch components. This is the single source of truth for every message exchanged between the daemon, relay, and mobile apps.

---

What is this

AgentWatch has multiple components written in different languages that communicate by passing structured JSON. Without a shared contract, schema drift occurs — a field added in one component is missed in others, validators diverge, and protocol changes have no clear record.

This package defines every message type in the system. TypeScript components import types and validators directly. iOS and Android developers use this repository as the specification for implementing equivalent Swift Codable structs and Kotlin data classes.

---

Installation

npm install @agent-watch/protocol
# or
yarn add @agent-watch/protocol

---

Contents

Core types

Type	Description
Session	A single agent conversation
AgentAction	A single agent tool call
ApprovalRequest	An action requiring the user's decision
ApprovalResponse	The user's decision, HMAC-signed by the phone
PushPayload	Encrypted envelope sent from daemon to relay
DeviceRegistration	Phone registration sent to the relay
HookInput	JSON the hook script validates from IDE stdin
HookOutput	The hook script's response to the IDE

Validators

Every type ships with a runtime JSON schema validator. Use them to validate untrusted input at component boundaries.

import {
  validateApprovalRequest,
  validateActionResponse,
} from "@agent-watch/protocol";

const reqResult = validateApprovalRequest(input);
if (!reqResult.success) {
  console.error(reqResult.errors);
}

const actionResult = validateActionResponse({ status: "disconnected" });
if (actionResult.success) {
  console.log(actionResult.data.status);
}

Also available as grouped validators:

import { validate } from "@agent-watch/protocol";

const result = validate.hookInput(parsed);

Versioning

Bump	Meaning	Action required
Major	Breaking change — field removed or type changed	Coordinated release across all components
Minor	New optional types added	Components update independently
Patch	Documentation or validator fixes only	Any component updates independently

---

Contributing

See CONTRIBUTING.md. Protocol changes must include updated type definitions, updated schema validators, updated mobile reference documentation, and a CHANGELOG entry.

---

Related repositories

• agentwatch-desktop — daemon, hook script, installer
• agentwatch-relay — self-hosted relay server
• agentwatch-ios — iOS app
• agentwatch-android — Android app

---

License

GNU Affero General Public License v3.0

Contributing

See CONTRIBUTING.md and CHANGELOG.md.