@clawrent/protocol 0.1.0 → 0.3.0

package/LICENSE

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) 2026 ClawRent
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
+AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
+LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
+OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
+PERFORMANCE OF THIS SOFTWARE.

package/dist/envelope.d.ts

@@ -25,6 +25,7 @@ export declare const ClawRentMessageSchema: z.ZodObject<{
     }>;
     type: z.ZodEnum<[string, ...string[]]>;
     payload: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    targetSlot: z.ZodOptional<z.ZodNumber>;
     signature: z.ZodOptional<z.ZodString>;
 }, "strip", z.ZodTypeAny, {
     type: string;
@@ -36,6 +37,7 @@ export declare const ClawRentMessageSchema: z.ZodObject<{
         agentId: string;
     };
     payload: Record<string, unknown>;
+    targetSlot?: number | undefined;
     signature?: string | undefined;
 }, {
     type: string;
@@ -47,6 +49,7 @@ export declare const ClawRentMessageSchema: z.ZodObject<{
         agentId: string;
     };
     payload: Record<string, unknown>;
+    targetSlot?: number | undefined;
     signature?: string | undefined;
 }>;
 export type ClawRentMessage = z.infer<typeof ClawRentMessageSchema>;

package/dist/envelope.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"envelope.d.ts","sourceRoot":"","sources":["../src/envelope.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAKxB,eAAO,MAAM,YAAY;;;;;;;;;EAGvB,CAAC;AAEH,eAAO,MAAM,qBAAqB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAQhC,CAAC;AAEH,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC"}
+{"version":3,"file":"envelope.d.ts","sourceRoot":"","sources":["../src/envelope.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAKxB,eAAO,MAAM,YAAY;;;;;;;;;EAGvB,CAAC;AAEH,eAAO,MAAM,qBAAqB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAShC,CAAC;AAEH,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC"}

package/dist/envelope.js

@@ -12,6 +12,7 @@ export const ClawRentMessageSchema = z.object({
     sender: SenderSchema,
     type: z.enum(allMessageTypes),
     payload: z.record(z.unknown()),
+    targetSlot: z.number().int().min(0).optional(),
     signature: z.string().optional(),
 });
 //# sourceMappingURL=envelope.js.map

package/dist/envelope.js.map

@@ -1 +1 @@
-{"version":3,"file":"envelope.js","sourceRoot":"","sources":["../src/envelope.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAEjD,MAAM,eAAe,GAAG,MAAM,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC;AAEnD,MAAM,CAAC,MAAM,YAAY,GAAG,CAAC,CAAC,MAAM,CAAC;IACnC,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,UAAU,EAAE,UAAU,EAAE,UAAU,EAAE,OAAO,CAAC,CAAC;IAC3D,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE;CACpB,CAAC,CAAC;AAEH,MAAM,CAAC,MAAM,qBAAqB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC5C,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE;IACd,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE;IACrB,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE;IACrB,MAAM,EAAE,YAAY;IACpB,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,eAAwC,CAAC;IACtD,OAAO,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC;IAC9B,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;CACjC,CAAC,CAAC"}
+{"version":3,"file":"envelope.js","sourceRoot":"","sources":["../src/envelope.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAEjD,MAAM,eAAe,GAAG,MAAM,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC;AAEnD,MAAM,CAAC,MAAM,YAAY,GAAG,CAAC,CAAC,MAAM,CAAC;IACnC,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,UAAU,EAAE,UAAU,EAAE,UAAU,EAAE,OAAO,CAAC,CAAC;IAC3D,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE;CACpB,CAAC,CAAC;AAEH,MAAM,CAAC,MAAM,qBAAqB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC5C,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE;IACd,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE;IACrB,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE;IACrB,MAAM,EAAE,YAAY;IACpB,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,eAAwC,CAAC;IACtD,OAAO,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC;IAC9B,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,EAAE;IAC9C,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;CACjC,CAAC,CAAC"}

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 export { MessageType } from './message-types.js';
 export { ClawRentMessageSchema, type ClawRentMessage } from './envelope.js';
+export { wsSessionMessageEventSchema, type WsSessionMessageEvent, wsSystemEventSchema, type WsSystemEvent, wsAgentControlEventSchema, type WsAgentControlEvent, } from './ws-events.js';
 export { ExecInstructionSchema, type ExecInstruction } from './instructions/exec.js';
 export { ReadFileInstructionSchema, type ReadFileInstruction } from './instructions/read-file.js';
 export { WriteFileInstructionSchema, type WriteFileInstruction } from './instructions/write-file.js';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACjD,OAAO,EAAE,qBAAqB,EAAE,KAAK,eAAe,EAAE,MAAM,eAAe,CAAC;AAC5E,OAAO,EAAE,qBAAqB,EAAE,KAAK,eAAe,EAAE,MAAM,wBAAwB,CAAC;AACrF,OAAO,EAAE,yBAAyB,EAAE,KAAK,mBAAmB,EAAE,MAAM,6BAA6B,CAAC;AAClG,OAAO,EAAE,0BAA0B,EAAE,KAAK,oBAAoB,EAAE,MAAM,8BAA8B,CAAC;AACrG,OAAO,EAAE,wBAAwB,EAAE,KAAK,kBAAkB,EAAE,MAAM,4BAA4B,CAAC;AAC/F,OAAO,EAAE,sBAAsB,EAAE,KAAK,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AACxF,OAAO,EAAE,mBAAmB,EAAE,KAAK,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAC/E,OAAO,EAAE,iBAAiB,EAAE,KAAK,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACzE,OAAO,EAAE,4BAA4B,EAAE,KAAK,sBAAsB,EAAE,MAAM,gCAAgC,CAAC;AAC3G,OAAO,EAAE,oBAAoB,EAAE,KAAK,cAAc,EAAE,MAAM,sBAAsB,CAAC;AACjF,OAAO,EAAE,qBAAqB,EAAE,KAAK,eAAe,EAAE,MAAM,uBAAuB,CAAC;AACpF,OAAO,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAClD,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAC7C,OAAO,EACL,qBAAqB,EACrB,KAAK,eAAe,EACpB,qBAAqB,EACrB,KAAK,eAAe,EACpB,gBAAgB,EAChB,KAAK,UAAU,EACf,wBAAwB,EACxB,KAAK,kBAAkB,EACvB,yBAAyB,EACzB,KAAK,mBAAmB,EACxB,wBAAwB,EACxB,KAAK,kBAAkB,GACxB,MAAM,qBAAqB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACjD,OAAO,EAAE,qBAAqB,EAAE,KAAK,eAAe,EAAE,MAAM,eAAe,CAAC;AAC5E,OAAO,EACL,2BAA2B,EAC3B,KAAK,qBAAqB,EAC1B,mBAAmB,EACnB,KAAK,aAAa,EAClB,yBAAyB,EACzB,KAAK,mBAAmB,GACzB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,qBAAqB,EAAE,KAAK,eAAe,EAAE,MAAM,wBAAwB,CAAC;AACrF,OAAO,EAAE,yBAAyB,EAAE,KAAK,mBAAmB,EAAE,MAAM,6BAA6B,CAAC;AAClG,OAAO,EAAE,0BAA0B,EAAE,KAAK,oBAAoB,EAAE,MAAM,8BAA8B,CAAC;AACrG,OAAO,EAAE,wBAAwB,EAAE,KAAK,kBAAkB,EAAE,MAAM,4BAA4B,CAAC;AAC/F,OAAO,EAAE,sBAAsB,EAAE,KAAK,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AACxF,OAAO,EAAE,mBAAmB,EAAE,KAAK,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAC/E,OAAO,EAAE,iBAAiB,EAAE,KAAK,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACzE,OAAO,EAAE,4BAA4B,EAAE,KAAK,sBAAsB,EAAE,MAAM,gCAAgC,CAAC;AAC3G,OAAO,EAAE,oBAAoB,EAAE,KAAK,cAAc,EAAE,MAAM,sBAAsB,CAAC;AACjF,OAAO,EAAE,qBAAqB,EAAE,KAAK,eAAe,EAAE,MAAM,uBAAuB,CAAC;AACpF,OAAO,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAClD,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAC7C,OAAO,EACL,qBAAqB,EACrB,KAAK,eAAe,EACpB,qBAAqB,EACrB,KAAK,eAAe,EACpB,gBAAgB,EAChB,KAAK,UAAU,EACf,wBAAwB,EACxB,KAAK,kBAAkB,EACvB,yBAAyB,EACzB,KAAK,mBAAmB,EACxB,wBAAwB,EACxB,KAAK,kBAAkB,GACxB,MAAM,qBAAqB,CAAC"}

package/dist/index.js

@@ -1,5 +1,6 @@
 export { MessageType } from './message-types.js';
 export { ClawRentMessageSchema } from './envelope.js';
+export { wsSessionMessageEventSchema, wsSystemEventSchema, wsAgentControlEventSchema, } from './ws-events.js';
 export { ExecInstructionSchema } from './instructions/exec.js';
 export { ReadFileInstructionSchema } from './instructions/read-file.js';
 export { WriteFileInstructionSchema } from './instructions/write-file.js';

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACjD,OAAO,EAAE,qBAAqB,EAAwB,MAAM,eAAe,CAAC;AAC5E,OAAO,EAAE,qBAAqB,EAAwB,MAAM,wBAAwB,CAAC;AACrF,OAAO,EAAE,yBAAyB,EAA4B,MAAM,6BAA6B,CAAC;AAClG,OAAO,EAAE,0BAA0B,EAA6B,MAAM,8BAA8B,CAAC;AACrG,OAAO,EAAE,wBAAwB,EAA2B,MAAM,4BAA4B,CAAC;AAC/F,OAAO,EAAE,sBAAsB,EAAyB,MAAM,yBAAyB,CAAC;AACxF,OAAO,EAAE,mBAAmB,EAAsB,MAAM,sBAAsB,CAAC;AAC/E,OAAO,EAAE,iBAAiB,EAAoB,MAAM,oBAAoB,CAAC;AACzE,OAAO,EAAE,4BAA4B,EAA+B,MAAM,gCAAgC,CAAC;AAC3G,OAAO,EAAE,oBAAoB,EAAuB,MAAM,sBAAsB,CAAC;AACjF,OAAO,EAAE,qBAAqB,EAAwB,MAAM,uBAAuB,CAAC;AACpF,OAAO,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAClD,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAC7C,OAAO,EACL,qBAAqB,EAErB,qBAAqB,EAErB,gBAAgB,EAEhB,wBAAwB,EAExB,yBAAyB,EAEzB,wBAAwB,GAEzB,MAAM,qBAAqB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACjD,OAAO,EAAE,qBAAqB,EAAwB,MAAM,eAAe,CAAC;AAC5E,OAAO,EACL,2BAA2B,EAE3B,mBAAmB,EAEnB,yBAAyB,GAE1B,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,qBAAqB,EAAwB,MAAM,wBAAwB,CAAC;AACrF,OAAO,EAAE,yBAAyB,EAA4B,MAAM,6BAA6B,CAAC;AAClG,OAAO,EAAE,0BAA0B,EAA6B,MAAM,8BAA8B,CAAC;AACrG,OAAO,EAAE,wBAAwB,EAA2B,MAAM,4BAA4B,CAAC;AAC/F,OAAO,EAAE,sBAAsB,EAAyB,MAAM,yBAAyB,CAAC;AACxF,OAAO,EAAE,mBAAmB,EAAsB,MAAM,sBAAsB,CAAC;AAC/E,OAAO,EAAE,iBAAiB,EAAoB,MAAM,oBAAoB,CAAC;AACzE,OAAO,EAAE,4BAA4B,EAA+B,MAAM,gCAAgC,CAAC;AAC3G,OAAO,EAAE,oBAAoB,EAAuB,MAAM,sBAAsB,CAAC;AACjF,OAAO,EAAE,qBAAqB,EAAwB,MAAM,uBAAuB,CAAC;AACpF,OAAO,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAClD,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAC7C,OAAO,EACL,qBAAqB,EAErB,qBAAqB,EAErB,gBAAgB,EAEhB,wBAAwB,EAExB,yBAAyB,EAEzB,wBAAwB,GAEzB,MAAM,qBAAqB,CAAC"}

package/dist/ws-events.d.ts

@@ -0,0 +1,202 @@
+import { z } from 'zod';
+/**
+ * /ws/session peer message frame — the forwardPayload pushed by the platform
+ * when a consumer or provider sends a dialogue/instruction/result message.
+ * Mirrors apps/platform-api/src/ws/ws-handler.ts (forwardPayload, ~L403-416):
+ *   { id, sessionId, timestamp, sender:{role,agentId,slotIndex?}, type, payload, _meta }
+ * `sender.agentId` is always present backend-side (agentId ?? userId).
+ */
+export declare const wsSessionMessageEventSchema: z.ZodObject<{
+    id: z.ZodString;
+    sessionId: z.ZodString;
+    timestamp: z.ZodNumber;
+    sender: z.ZodObject<{
+        role: z.ZodEnum<["provider", "consumer", "platform", "staff"]>;
+        agentId: z.ZodString;
+        slotIndex: z.ZodOptional<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        role: "provider" | "consumer" | "platform" | "staff";
+        agentId: string;
+        slotIndex?: number | undefined;
+    }, {
+        role: "provider" | "consumer" | "platform" | "staff";
+        agentId: string;
+        slotIndex?: number | undefined;
+    }>;
+    type: z.ZodString;
+    payload: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    _meta: z.ZodObject<{
+        sessionId: z.ZodString;
+        senderRole: z.ZodString;
+        slotIndex: z.ZodOptional<z.ZodNumber>;
+        timestamp: z.ZodString;
+    }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+        sessionId: z.ZodString;
+        senderRole: z.ZodString;
+        slotIndex: z.ZodOptional<z.ZodNumber>;
+        timestamp: z.ZodString;
+    }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+        sessionId: z.ZodString;
+        senderRole: z.ZodString;
+        slotIndex: z.ZodOptional<z.ZodNumber>;
+        timestamp: z.ZodString;
+    }, z.ZodTypeAny, "passthrough">>;
+}, "strip", z.ZodTypeAny, {
+    type: string;
+    id: string;
+    sessionId: string;
+    timestamp: number;
+    sender: {
+        role: "provider" | "consumer" | "platform" | "staff";
+        agentId: string;
+        slotIndex?: number | undefined;
+    };
+    payload: Record<string, unknown>;
+    _meta: {
+        sessionId: string;
+        timestamp: string;
+        senderRole: string;
+        slotIndex?: number | undefined;
+    } & {
+        [k: string]: unknown;
+    };
+}, {
+    type: string;
+    id: string;
+    sessionId: string;
+    timestamp: number;
+    sender: {
+        role: "provider" | "consumer" | "platform" | "staff";
+        agentId: string;
+        slotIndex?: number | undefined;
+    };
+    payload: Record<string, unknown>;
+    _meta: {
+        sessionId: string;
+        timestamp: string;
+        senderRole: string;
+        slotIndex?: number | undefined;
+    } & {
+        [k: string]: unknown;
+    };
+}>;
+export type WsSessionMessageEvent = z.infer<typeof wsSessionMessageEventSchema>;
+/**
+ * /ws/session system.* events. Types confirmed in backend:
+ * peer_connected/peer_disconnected (ws-handler.ts), peer_offline (ws-handler.ts),
+ * blocked (ws-handler.ts security gateway), error (ws-agent-handler.ts / ws-handler.ts),
+ * session_ended (client-manager.ts closeSessionClients — carries `reason`).
+ */
+export declare const wsSystemEventSchema: z.ZodObject<{
+    type: z.ZodEnum<["system.peer_connected", "system.peer_disconnected", "system.peer_offline", "system.blocked", "system.error", "system.session_ended"]>;
+    sessionId: z.ZodOptional<z.ZodString>;
+    payload: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, "strip", z.ZodTypeAny, {
+    type: "system.peer_connected" | "system.peer_disconnected" | "system.peer_offline" | "system.blocked" | "system.error" | "system.session_ended";
+    sessionId?: string | undefined;
+    payload?: Record<string, unknown> | undefined;
+}, {
+    type: "system.peer_connected" | "system.peer_disconnected" | "system.peer_offline" | "system.blocked" | "system.error" | "system.session_ended";
+    sessionId?: string | undefined;
+    payload?: Record<string, unknown> | undefined;
+}>;
+export type WsSystemEvent = z.infer<typeof wsSystemEventSchema>;
+/**
+ * /ws/agent control channel events delivered via `sendToAgent(agentId, {type, payload})`.
+ * Discriminator is `type` (not `event`) and fields live under `payload` — confirmed at
+ * sessions.routes.ts:201-212 / 572-580 and orders.routes.ts:229-237.
+ *
+ * Note: backend does NOT push `session.ended` on /ws/agent. Session terminations arrive
+ * as `system.session_ended` on /ws/session (see wsSystemEventSchema).
+ */
+export declare const wsAgentControlEventSchema: z.ZodDiscriminatedUnion<"type", [z.ZodObject<{
+    type: z.ZodLiteral<"session.new">;
+    payload: z.ZodObject<{
+        sessionId: z.ZodString;
+        sessionToken: z.ZodOptional<z.ZodString>;
+        status: z.ZodOptional<z.ZodString>;
+        consumerUserId: z.ZodOptional<z.ZodString>;
+        taskDescription: z.ZodOptional<z.ZodString>;
+        pricingSnapshot: z.ZodOptional<z.ZodUnknown>;
+        orderId: z.ZodOptional<z.ZodString>;
+        timestamp: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        sessionId: string;
+        status?: string | undefined;
+        timestamp?: string | undefined;
+        sessionToken?: string | undefined;
+        consumerUserId?: string | undefined;
+        taskDescription?: string | undefined;
+        pricingSnapshot?: unknown;
+        orderId?: string | undefined;
+    }, {
+        sessionId: string;
+        status?: string | undefined;
+        timestamp?: string | undefined;
+        sessionToken?: string | undefined;
+        consumerUserId?: string | undefined;
+        taskDescription?: string | undefined;
+        pricingSnapshot?: unknown;
+        orderId?: string | undefined;
+    }>;
+}, "strip", z.ZodTypeAny, {
+    type: "session.new";
+    payload: {
+        sessionId: string;
+        status?: string | undefined;
+        timestamp?: string | undefined;
+        sessionToken?: string | undefined;
+        consumerUserId?: string | undefined;
+        taskDescription?: string | undefined;
+        pricingSnapshot?: unknown;
+        orderId?: string | undefined;
+    };
+}, {
+    type: "session.new";
+    payload: {
+        sessionId: string;
+        status?: string | undefined;
+        timestamp?: string | undefined;
+        sessionToken?: string | undefined;
+        consumerUserId?: string | undefined;
+        taskDescription?: string | undefined;
+        pricingSnapshot?: unknown;
+        orderId?: string | undefined;
+    };
+}>, z.ZodObject<{
+    type: z.ZodLiteral<"session.approved">;
+    payload: z.ZodObject<{
+        sessionId: z.ZodString;
+        sessionToken: z.ZodOptional<z.ZodString>;
+        status: z.ZodOptional<z.ZodString>;
+        timestamp: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        sessionId: string;
+        status?: string | undefined;
+        timestamp?: string | undefined;
+        sessionToken?: string | undefined;
+    }, {
+        sessionId: string;
+        status?: string | undefined;
+        timestamp?: string | undefined;
+        sessionToken?: string | undefined;
+    }>;
+}, "strip", z.ZodTypeAny, {
+    type: "session.approved";
+    payload: {
+        sessionId: string;
+        status?: string | undefined;
+        timestamp?: string | undefined;
+        sessionToken?: string | undefined;
+    };
+}, {
+    type: "session.approved";
+    payload: {
+        sessionId: string;
+        status?: string | undefined;
+        timestamp?: string | undefined;
+        sessionToken?: string | undefined;
+    };
+}>]>;
+export type WsAgentControlEvent = z.infer<typeof wsAgentControlEventSchema>;
+//# sourceMappingURL=ws-events.d.ts.map

package/dist/ws-events.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ws-events.d.ts","sourceRoot":"","sources":["../src/ws-events.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;;;GAMG;AACH,eAAO,MAAM,2BAA2B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAmBtC,CAAC;AACH,MAAM,MAAM,qBAAqB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,2BAA2B,CAAC,CAAC;AAEhF;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB;;;;;;;;;;;;EAW9B,CAAC;AACH,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAEhE;;;;;;;GAOG;AACH,eAAO,MAAM,yBAAyB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;IAuBpC,CAAC;AACH,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,yBAAyB,CAAC,CAAC"}

package/dist/ws-events.js

@@ -0,0 +1,79 @@
+import { z } from 'zod';
+/**
+ * /ws/session peer message frame — the forwardPayload pushed by the platform
+ * when a consumer or provider sends a dialogue/instruction/result message.
+ * Mirrors apps/platform-api/src/ws/ws-handler.ts (forwardPayload, ~L403-416):
+ *   { id, sessionId, timestamp, sender:{role,agentId,slotIndex?}, type, payload, _meta }
+ * `sender.agentId` is always present backend-side (agentId ?? userId).
+ */
+export const wsSessionMessageEventSchema = z.object({
+    id: z.string(),
+    sessionId: z.string(),
+    timestamp: z.number(),
+    sender: z.object({
+        role: z.enum(['provider', 'consumer', 'platform', 'staff']),
+        agentId: z.string(),
+        slotIndex: z.number().int().min(0).optional(),
+    }),
+    type: z.string(),
+    payload: z.record(z.unknown()),
+    _meta: z
+        .object({
+        sessionId: z.string(),
+        senderRole: z.string(),
+        slotIndex: z.number().int().min(0).optional(),
+        timestamp: z.string(),
+    })
+        .passthrough(),
+});
+/**
+ * /ws/session system.* events. Types confirmed in backend:
+ * peer_connected/peer_disconnected (ws-handler.ts), peer_offline (ws-handler.ts),
+ * blocked (ws-handler.ts security gateway), error (ws-agent-handler.ts / ws-handler.ts),
+ * session_ended (client-manager.ts closeSessionClients — carries `reason`).
+ */
+export const wsSystemEventSchema = z.object({
+    type: z.enum([
+        'system.peer_connected',
+        'system.peer_disconnected',
+        'system.peer_offline',
+        'system.blocked',
+        'system.error',
+        'system.session_ended',
+    ]),
+    sessionId: z.string().optional(),
+    payload: z.record(z.unknown()).optional(),
+});
+/**
+ * /ws/agent control channel events delivered via `sendToAgent(agentId, {type, payload})`.
+ * Discriminator is `type` (not `event`) and fields live under `payload` — confirmed at
+ * sessions.routes.ts:201-212 / 572-580 and orders.routes.ts:229-237.
+ *
+ * Note: backend does NOT push `session.ended` on /ws/agent. Session terminations arrive
+ * as `system.session_ended` on /ws/session (see wsSystemEventSchema).
+ */
+export const wsAgentControlEventSchema = z.discriminatedUnion('type', [
+    z.object({
+        type: z.literal('session.new'),
+        payload: z.object({
+            sessionId: z.string(),
+            sessionToken: z.string().optional(),
+            status: z.string().optional(),
+            consumerUserId: z.string().optional(),
+            taskDescription: z.string().optional(),
+            pricingSnapshot: z.unknown().optional(),
+            orderId: z.string().optional(),
+            timestamp: z.string().optional(),
+        }),
+    }),
+    z.object({
+        type: z.literal('session.approved'),
+        payload: z.object({
+            sessionId: z.string(),
+            sessionToken: z.string().optional(),
+            status: z.string().optional(),
+            timestamp: z.string().optional(),
+        }),
+    }),
+]);
+//# sourceMappingURL=ws-events.js.map

package/dist/ws-events.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ws-events.js","sourceRoot":"","sources":["../src/ws-events.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clawrent/protocol",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -21,12 +21,14 @@
   },
   "devDependencies": {
     "typescript": "^5.7.0",
-    "@clawrent/config": "0.1.0",
-    "@clawrent/shared-types": "0.1.0"
+    "vitest": "^3.0.0",
+    "@clawrent/shared-types": "0.2.0",
+    "@clawrent/config": "0.1.0"
   },
   "scripts": {
-    "build": "tsc",
+    "build": "tsc -p tsconfig.build.json",
     "typecheck": "tsc --noEmit",
+    "test": "vitest run",
     "lint": "eslint src/"
   }
 }