@dungle-scrubs/tether-protocol 0.1.0

package/dist/websocket.d.ts

@@ -0,0 +1,215 @@
+import { z } from "zod";
+import type { SessionEvent } from "./records.js";
+/** WebSocket task-claim command schema. */
+export declare const wsTaskClaimMessageSchema: z.ZodObject<{
+    op: z.ZodLiteral<"task.claim">;
+    requestId: z.ZodOptional<z.ZodString>;
+    taskId: z.ZodString;
+}, z.core.$strip>;
+/** WebSocket task claim-refresh command schema. */
+export declare const wsTaskRefreshMessageSchema: z.ZodObject<{
+    op: z.ZodLiteral<"task.refresh">;
+    requestId: z.ZodOptional<z.ZodString>;
+    taskId: z.ZodString;
+}, z.core.$strip>;
+/** WebSocket task-cancel command schema. */
+export declare const wsTaskCancelMessageSchema: z.ZodObject<{
+    op: z.ZodLiteral<"task.cancel">;
+    reason: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    requestId: z.ZodOptional<z.ZodString>;
+    taskId: z.ZodString;
+}, z.core.$strip>;
+/** WebSocket task-complete command schema. */
+export declare const wsTaskCompleteMessageSchema: z.ZodObject<{
+    op: z.ZodLiteral<"task.complete">;
+    requestId: z.ZodOptional<z.ZodString>;
+    result: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    taskId: z.ZodString;
+}, z.core.$strip>;
+/** WebSocket task-fail command schema. */
+export declare const wsTaskFailMessageSchema: z.ZodObject<{
+    failure: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    op: z.ZodLiteral<"task.fail">;
+    requestId: z.ZodOptional<z.ZodString>;
+    taskId: z.ZodString;
+}, z.core.$strip>;
+/** WebSocket task-release command schema. */
+export declare const wsTaskReleaseMessageSchema: z.ZodObject<{
+    op: z.ZodLiteral<"task.release">;
+    requestId: z.ZodOptional<z.ZodString>;
+    taskId: z.ZodString;
+}, z.core.$strip>;
+/** WebSocket publish command schema. */
+export declare const wsPublishMessageSchema: z.ZodObject<{
+    eventId: z.ZodOptional<z.ZodString>;
+    op: z.ZodLiteral<"publish">;
+    payload: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    producerId: z.ZodString;
+    requestId: z.ZodOptional<z.ZodString>;
+    type: z.ZodString;
+}, z.core.$strip>;
+/** WebSocket server event envelope schema. */
+export declare const webSocketEventEnvelopeSchema: z.ZodObject<{
+    event: z.ZodObject<{
+        createdAt: z.ZodString;
+        eventId: z.ZodString;
+        payload: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+        producerId: z.ZodString;
+        seq: z.ZodNumber;
+        sessionId: z.ZodString;
+        type: z.ZodPipe<z.ZodString, z.ZodTransform<(string & {}) | "agent.output" | "approval.recorded" | "control.cancel" | "participant.heartbeat" | "participant.joined" | "participant.updated" | "session.created" | "task.claim_expired" | "task.claimed" | "task.completed" | "task.created" | "task.failed" | "task.progress" | "task.released" | "user.message", string>>;
+    }, z.core.$strip>;
+    op: z.ZodLiteral<"event">;
+}, z.core.$strip>;
+/** WebSocket replay-complete envelope schema. */
+export declare const webSocketReplayCompleteEnvelopeSchema: z.ZodObject<{
+    op: z.ZodLiteral<"replay.complete">;
+}, z.core.$strip>;
+/** WebSocket command-result envelope schema. */
+export declare const webSocketCommandResultEnvelopeSchema: z.ZodObject<{
+    command: z.ZodString;
+    op: z.ZodLiteral<"command.result">;
+    requestId: z.ZodOptional<z.ZodString>;
+    task: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+        cancelledAt: z.ZodNullable<z.ZodString>;
+        claimExpiredAt: z.ZodNullable<z.ZodString>;
+        claimExpiredBy: z.ZodNullable<z.ZodString>;
+        claimExpiresAt: z.ZodNullable<z.ZodString>;
+        claimedAt: z.ZodNullable<z.ZodString>;
+        claimedBy: z.ZodNullable<z.ZodString>;
+        completedAt: z.ZodNullable<z.ZodString>;
+        createdAt: z.ZodString;
+        failedAt: z.ZodNullable<z.ZodString>;
+        failure: z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        input: z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        kind: z.ZodString;
+        objective: z.ZodString;
+        releasedAt: z.ZodNullable<z.ZodString>;
+        releasedBy: z.ZodNullable<z.ZodString>;
+        result: z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        sessionId: z.ZodString;
+        taskId: z.ZodString;
+    }, z.core.$strip>>>;
+}, z.core.$loose>;
+/** WebSocket error envelope schema. */
+export declare const webSocketErrorEnvelopeSchema: z.ZodObject<{
+    error: z.ZodString;
+    op: z.ZodLiteral<"error">;
+    requestId: z.ZodOptional<z.ZodString>;
+}, z.core.$loose>;
+/** Runtime validator for server-to-client WebSocket envelopes. */
+export declare const webSocketServerEnvelopeSchema: z.ZodUnion<readonly [z.ZodObject<{
+    command: z.ZodString;
+    op: z.ZodLiteral<"command.result">;
+    requestId: z.ZodOptional<z.ZodString>;
+    task: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+        cancelledAt: z.ZodNullable<z.ZodString>;
+        claimExpiredAt: z.ZodNullable<z.ZodString>;
+        claimExpiredBy: z.ZodNullable<z.ZodString>;
+        claimExpiresAt: z.ZodNullable<z.ZodString>;
+        claimedAt: z.ZodNullable<z.ZodString>;
+        claimedBy: z.ZodNullable<z.ZodString>;
+        completedAt: z.ZodNullable<z.ZodString>;
+        createdAt: z.ZodString;
+        failedAt: z.ZodNullable<z.ZodString>;
+        failure: z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        input: z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        kind: z.ZodString;
+        objective: z.ZodString;
+        releasedAt: z.ZodNullable<z.ZodString>;
+        releasedBy: z.ZodNullable<z.ZodString>;
+        result: z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        sessionId: z.ZodString;
+        taskId: z.ZodString;
+    }, z.core.$strip>>>;
+}, z.core.$loose>, z.ZodObject<{
+    error: z.ZodString;
+    op: z.ZodLiteral<"error">;
+    requestId: z.ZodOptional<z.ZodString>;
+}, z.core.$loose>, z.ZodObject<{
+    event: z.ZodObject<{
+        createdAt: z.ZodString;
+        eventId: z.ZodString;
+        payload: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+        producerId: z.ZodString;
+        seq: z.ZodNumber;
+        sessionId: z.ZodString;
+        type: z.ZodPipe<z.ZodString, z.ZodTransform<(string & {}) | "agent.output" | "approval.recorded" | "control.cancel" | "participant.heartbeat" | "participant.joined" | "participant.updated" | "session.created" | "task.claim_expired" | "task.claimed" | "task.completed" | "task.created" | "task.failed" | "task.progress" | "task.released" | "user.message", string>>;
+    }, z.core.$strip>;
+    op: z.ZodLiteral<"event">;
+}, z.core.$strip>, z.ZodObject<{
+    op: z.ZodLiteral<"replay.complete">;
+}, z.core.$strip>]>;
+/** Parsed WebSocket command-result envelope. */
+export type CommandResultEnvelope = z.infer<typeof webSocketCommandResultEnvelopeSchema>;
+/** Parsed server-to-client WebSocket envelope. */
+export type WebSocketServerEnvelope = z.infer<typeof webSocketServerEnvelopeSchema>;
+/** Parsed WebSocket task command message. */
+export type WebSocketTaskCommandMessage = z.infer<typeof wsTaskCancelMessageSchema> | z.infer<typeof wsTaskClaimMessageSchema> | z.infer<typeof wsTaskCompleteMessageSchema> | z.infer<typeof wsTaskFailMessageSchema> | z.infer<typeof wsTaskRefreshMessageSchema> | z.infer<typeof wsTaskReleaseMessageSchema>;
+/**
+ * WebSocket client command messages that can be correlated with a command
+ * result envelope.
+ */
+export type WebSocketCommandMessage = WebSocketTaskCommandMessage | z.infer<typeof wsPublishMessageSchema>;
+interface SerializeCommandEnvelopeInput {
+    readonly command: string;
+    readonly payload: Record<string, unknown>;
+    readonly requestId?: string;
+}
+interface SerializeErrorEnvelopeInput {
+    readonly details?: Record<string, unknown>;
+    readonly error: string;
+    readonly requestId?: string;
+}
+/** Creates a WebSocket publish message for participant-originated events. */
+export declare function buildWsPublishMessage(input: {
+    readonly eventId?: string;
+    readonly payload: Record<string, unknown>;
+    readonly producerId: string;
+    readonly requestId?: string;
+    readonly type: string;
+}): z.infer<typeof wsPublishMessageSchema>;
+/** Creates a WebSocket task-claim command. */
+export declare function buildWsTaskClaimMessage(input: {
+    readonly requestId?: string;
+    readonly taskId: string;
+}): z.infer<typeof wsTaskClaimMessageSchema>;
+/** Creates a WebSocket task claim-refresh command. */
+export declare function buildWsTaskRefreshMessage(input: {
+    readonly requestId?: string;
+    readonly taskId: string;
+}): z.infer<typeof wsTaskRefreshMessageSchema>;
+/** Creates a WebSocket task-cancel command. */
+export declare function buildWsTaskCancelMessage(input: {
+    readonly reason?: Record<string, unknown>;
+    readonly requestId?: string;
+    readonly taskId: string;
+}): z.infer<typeof wsTaskCancelMessageSchema>;
+/** Creates a WebSocket task-complete command. */
+export declare function buildWsTaskCompleteMessage(input: {
+    readonly requestId?: string;
+    readonly result: Record<string, unknown>;
+    readonly taskId: string;
+}): z.infer<typeof wsTaskCompleteMessageSchema>;
+/** Creates a WebSocket task-fail command. */
+export declare function buildWsTaskFailMessage(input: {
+    readonly failure: Record<string, unknown>;
+    readonly requestId?: string;
+    readonly taskId: string;
+}): z.infer<typeof wsTaskFailMessageSchema>;
+/** Creates a WebSocket task-release command. */
+export declare function buildWsTaskReleaseMessage(input: {
+    readonly requestId?: string;
+    readonly taskId: string;
+}): z.infer<typeof wsTaskReleaseMessageSchema>;
+/** Parses server-to-client WebSocket envelopes into the known protocol union. */
+export declare function parseWebSocketServerEnvelope(value: unknown): WebSocketServerEnvelope | null;
+/** Serializes a session event envelope for WebSocket subscribers. */
+export declare function serializeEventEnvelope(event: SessionEvent): string;
+/** Serializes the replay-complete marker sent after historical events. */
+export declare function serializeReplayCompleteEnvelope(): string;
+/** Serializes a command result envelope while preserving command-specific fields. */
+export declare function serializeCommandResultEnvelope(input: SerializeCommandEnvelopeInput): string;
+/** Serializes a command or connection error envelope. */
+export declare function serializeErrorEnvelope(input: SerializeErrorEnvelopeInput): string;
+export {};

package/dist/websocket.js

@@ -0,0 +1,177 @@
+import { z } from "zod";
+import { sessionEventSchema } from "./event-builders.js";
+import { taskRecordSchema, webSocketOperation } from "./records.js";
+/** WebSocket task-claim command schema. */
+export const wsTaskClaimMessageSchema = z.object({
+    op: z.literal(webSocketOperation.taskClaim),
+    requestId: z.string().min(1).optional(),
+    taskId: z.string().min(1),
+});
+/** WebSocket task claim-refresh command schema. */
+export const wsTaskRefreshMessageSchema = z.object({
+    op: z.literal(webSocketOperation.taskRefresh),
+    requestId: z.string().min(1).optional(),
+    taskId: z.string().min(1),
+});
+/** WebSocket task-cancel command schema. */
+export const wsTaskCancelMessageSchema = z.object({
+    op: z.literal(webSocketOperation.taskCancel),
+    reason: z.record(z.string(), z.unknown()).default({}),
+    requestId: z.string().min(1).optional(),
+    taskId: z.string().min(1),
+});
+/** WebSocket task-complete command schema. */
+export const wsTaskCompleteMessageSchema = z.object({
+    op: z.literal(webSocketOperation.taskComplete),
+    requestId: z.string().min(1).optional(),
+    result: z.record(z.string(), z.unknown()).default({}),
+    taskId: z.string().min(1),
+});
+/** WebSocket task-fail command schema. */
+export const wsTaskFailMessageSchema = z.object({
+    failure: z.record(z.string(), z.unknown()).default({}),
+    op: z.literal(webSocketOperation.taskFail),
+    requestId: z.string().min(1).optional(),
+    taskId: z.string().min(1),
+});
+/** WebSocket task-release command schema. */
+export const wsTaskReleaseMessageSchema = z.object({
+    op: z.literal(webSocketOperation.taskRelease),
+    requestId: z.string().min(1).optional(),
+    taskId: z.string().min(1),
+});
+/** WebSocket publish command schema. */
+export const wsPublishMessageSchema = z.object({
+    eventId: z.string().min(1).optional(),
+    op: z.literal(webSocketOperation.publish),
+    payload: z.record(z.string(), z.unknown()).default({}),
+    producerId: z.string().min(1),
+    requestId: z.string().min(1).optional(),
+    type: z.string().min(1),
+});
+/** WebSocket server event envelope schema. */
+export const webSocketEventEnvelopeSchema = z.object({
+    event: sessionEventSchema,
+    op: z.literal(webSocketOperation.event),
+});
+/** WebSocket replay-complete envelope schema. */
+export const webSocketReplayCompleteEnvelopeSchema = z.object({
+    op: z.literal(webSocketOperation.replayComplete),
+});
+/** WebSocket command-result envelope schema. */
+export const webSocketCommandResultEnvelopeSchema = z
+    .object({
+    command: z.string().min(1),
+    op: z.literal(webSocketOperation.commandResult),
+    requestId: z.string().min(1).optional(),
+    task: taskRecordSchema.nullable().optional(),
+})
+    .passthrough();
+/** WebSocket error envelope schema. */
+export const webSocketErrorEnvelopeSchema = z
+    .object({
+    error: z.string(),
+    op: z.literal(webSocketOperation.error),
+    requestId: z.string().min(1).optional(),
+})
+    .passthrough();
+/** Runtime validator for server-to-client WebSocket envelopes. */
+export const webSocketServerEnvelopeSchema = z.union([
+    webSocketCommandResultEnvelopeSchema,
+    webSocketErrorEnvelopeSchema,
+    webSocketEventEnvelopeSchema,
+    webSocketReplayCompleteEnvelopeSchema,
+]);
+/** Creates a WebSocket publish message for participant-originated events. */
+export function buildWsPublishMessage(input) {
+    return {
+        ...(input.eventId !== undefined ? { eventId: input.eventId } : {}),
+        op: webSocketOperation.publish,
+        payload: input.payload,
+        producerId: input.producerId,
+        ...(input.requestId !== undefined ? { requestId: input.requestId } : {}),
+        type: input.type,
+    };
+}
+/** Creates a WebSocket task-claim command. */
+export function buildWsTaskClaimMessage(input) {
+    return {
+        op: webSocketOperation.taskClaim,
+        ...(input.requestId !== undefined ? { requestId: input.requestId } : {}),
+        taskId: input.taskId,
+    };
+}
+/** Creates a WebSocket task claim-refresh command. */
+export function buildWsTaskRefreshMessage(input) {
+    return {
+        op: webSocketOperation.taskRefresh,
+        ...(input.requestId !== undefined ? { requestId: input.requestId } : {}),
+        taskId: input.taskId,
+    };
+}
+/** Creates a WebSocket task-cancel command. */
+export function buildWsTaskCancelMessage(input) {
+    return {
+        op: webSocketOperation.taskCancel,
+        reason: input.reason ?? {},
+        ...(input.requestId !== undefined ? { requestId: input.requestId } : {}),
+        taskId: input.taskId,
+    };
+}
+/** Creates a WebSocket task-complete command. */
+export function buildWsTaskCompleteMessage(input) {
+    return {
+        op: webSocketOperation.taskComplete,
+        ...(input.requestId !== undefined ? { requestId: input.requestId } : {}),
+        result: input.result,
+        taskId: input.taskId,
+    };
+}
+/** Creates a WebSocket task-fail command. */
+export function buildWsTaskFailMessage(input) {
+    return {
+        failure: input.failure,
+        op: webSocketOperation.taskFail,
+        ...(input.requestId !== undefined ? { requestId: input.requestId } : {}),
+        taskId: input.taskId,
+    };
+}
+/** Creates a WebSocket task-release command. */
+export function buildWsTaskReleaseMessage(input) {
+    return {
+        op: webSocketOperation.taskRelease,
+        ...(input.requestId !== undefined ? { requestId: input.requestId } : {}),
+        taskId: input.taskId,
+    };
+}
+/** Parses server-to-client WebSocket envelopes into the known protocol union. */
+export function parseWebSocketServerEnvelope(value) {
+    const parsed = webSocketServerEnvelopeSchema.safeParse(value);
+    return parsed.success ? parsed.data : null;
+}
+/** Serializes a session event envelope for WebSocket subscribers. */
+export function serializeEventEnvelope(event) {
+    return JSON.stringify({ event, op: webSocketOperation.event });
+}
+/** Serializes the replay-complete marker sent after historical events. */
+export function serializeReplayCompleteEnvelope() {
+    return JSON.stringify({ op: webSocketOperation.replayComplete });
+}
+/** Serializes a command result envelope while preserving command-specific fields. */
+export function serializeCommandResultEnvelope(input) {
+    return JSON.stringify({
+        ...input.payload,
+        command: input.command,
+        op: webSocketOperation.commandResult,
+        ...(input.requestId !== undefined ? { requestId: input.requestId } : {}),
+    });
+}
+/** Serializes a command or connection error envelope. */
+export function serializeErrorEnvelope(input) {
+    return JSON.stringify({
+        ...(input.details ?? {}),
+        error: input.error,
+        op: webSocketOperation.error,
+        ...(input.requestId !== undefined ? { requestId: input.requestId } : {}),
+    });
+}

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@dungle-scrubs/tether-protocol",
+  "version": "0.1.0",
+  "description": "Shared Tether protocol records, validators, and event builders.",
+  "license": "MIT",
+  "author": "Kevin Frilot",
+  "homepage": "https://github.com/dungle-scrubs/tether/tree/main/packages/protocol#readme",
+  "bugs": "https://github.com/dungle-scrubs/tether/issues",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/dungle-scrubs/tether.git",
+    "directory": "packages/protocol"
+  },
+  "type": "module",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "format": "biome format --config-path=../../tooling/biome.json --write .",
+    "format:check": "biome format --config-path=../../tooling/biome.json .",
+    "lint": "biome lint --config-path=../../tooling/biome.json .",
+    "prepublishOnly": "pnpm run build",
+    "test": "vitest run",
+    "typecheck": "tsc -p tsconfig.json --noEmit && tsc -p tsconfig.test.json"
+  },
+  "dependencies": {
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "@types/node": "^25.9.1",
+    "vitest": "^4.1.7"
+  }
+}