@dungle-scrubs/tether-protocol 0.1.0

package/dist/event-builders.d.ts

@@ -0,0 +1,244 @@
+import { z } from "zod";
+import type { ParticipantRecord, SessionEvent, SessionEventType, TaskRecord } from "./records.js";
+import { approvalDecisionSchema } from "./rest-schemas.js";
+/** Payload schema for task-created events. */
+export declare const taskCreatedPayloadSchema: z.ZodObject<{
+    task: 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.$strip>;
+/** Payload schema for task-claim-expired events. */
+export declare const taskClaimExpiredPayloadSchema: z.ZodObject<{
+    previousClaimedBy: z.ZodString;
+    task: 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.$strip>;
+/** Payload schema for task participant lifecycle events that include a task. */
+export declare const taskParticipantPayloadSchema: z.ZodObject<{
+    participantId: z.ZodString;
+    task: 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.$strip>;
+/** Payload schema for task cancellation events. */
+export declare const taskCancelledPayloadSchema: z.ZodObject<{
+    participantId: z.ZodString;
+    reason: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    task: 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.$strip>;
+/** Event payload schema for task approval decisions. */
+export declare const taskApprovalRecordedPayloadSchema: z.ZodObject<{
+    decision: z.ZodUnion<readonly [z.ZodLiteral<"approved">, z.ZodLiteral<"rejected">]>;
+    participantId: z.ZodString;
+    reason: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    task: 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.$strip>;
+/** Runtime validator for public session events. */
+export declare const sessionEventSchema: 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>;
+/** Input for appending a canonical session event. */
+export interface AppendSessionEventInput {
+    readonly eventId: string;
+    readonly payload: Record<string, unknown>;
+    readonly producerId: string;
+    readonly sessionId: string;
+    readonly type: SessionEventType;
+}
+type BuildParticipantEventInput = {
+    readonly participant: ParticipantRecord;
+    readonly sessionId: string;
+    readonly status: "joined" | "refreshed";
+} | {
+    readonly participant: ParticipantRecord;
+    readonly previousParticipant: ParticipantRecord;
+    readonly sessionId: string;
+    readonly status: "updated";
+};
+interface BuildTaskParticipantEventInput {
+    readonly participantId: string;
+    readonly sessionId: string;
+    readonly task: TaskRecord;
+}
+interface BuildTaskCancelledEventInput extends BuildTaskParticipantEventInput {
+    readonly reason: Record<string, unknown>;
+}
+interface BuildTaskApprovalRecordedEventInput extends BuildTaskParticipantEventInput {
+    readonly decision: z.infer<typeof approvalDecisionSchema>;
+    readonly reason: Record<string, unknown>;
+}
+interface BuildTaskCreatedEventInput {
+    readonly sessionId: string;
+    readonly task: TaskRecord;
+}
+interface BuildTaskClaimExpiredEventInput {
+    readonly previousClaimedBy: string;
+    readonly sessionId: string;
+    readonly task: TaskRecord;
+}
+interface BuildPublishedEventInput {
+    readonly eventId?: string;
+    readonly payload: Record<string, unknown>;
+    readonly producerId: string;
+    readonly sessionId: string;
+    readonly type: string;
+}
+interface BuildTaskOutputEventInput {
+    readonly output: string;
+    readonly participantId: string;
+    readonly sessionId: string;
+    readonly taskId: string;
+}
+interface BuildTaskProgressEventInput {
+    readonly participantId: string;
+    readonly sessionId: string;
+    readonly taskId: string;
+}
+/** Creates a unique event id in Tether's public event-id namespace. */
+export declare function newEventId(): string;
+/** Creates a participant id scoped by runtime kind for generated REST participants. */
+export declare function newParticipantId(runtimeKind: string): string;
+/** Creates a unique runtime instance id. */
+export declare function newParticipantInstanceId(): string;
+/** Creates a unique session id. */
+export declare function newSessionId(): string;
+/** Creates a unique task id. */
+export declare function newTaskId(): string;
+/** Parses an event replay cursor, falling back to the beginning of the stream. */
+export declare function parseAfterSeq(value: string | null | undefined): number;
+/** Parses a positive safe integer without coercing partial decimal strings. */
+export declare function parsePositiveSafeInteger(value: string | number | bigint | null | undefined): number | null;
+/** Builds the durable event for a newly-created session. */
+export declare function buildSessionCreatedEventInput(sessionId: string): AppendSessionEventInput;
+/** Builds a caller-published session event while applying Tether id defaults. */
+export declare function buildPublishedEventInput(input: BuildPublishedEventInput): AppendSessionEventInput;
+/** Builds participant join/update events. */
+export declare function buildParticipantRegistrationEventInput(input: BuildParticipantEventInput): AppendSessionEventInput | null;
+/** Builds the visible heartbeat event emitted after presence state refreshes. */
+export declare function buildParticipantHeartbeatEventInput(input: {
+    readonly participant: ParticipantRecord;
+    readonly sessionId: string;
+}): AppendSessionEventInput;
+/** Builds the canonical event for a newly-created task. */
+export declare function buildTaskCreatedEventInput(input: BuildTaskCreatedEventInput): AppendSessionEventInput;
+/** Builds the canonical event for a user or bridge approval decision. */
+export declare function buildTaskApprovalRecordedEventInput(input: BuildTaskApprovalRecordedEventInput): AppendSessionEventInput;
+/** Builds the canonical event for a successful task claim. */
+export declare function buildTaskClaimedEventInput(input: BuildTaskParticipantEventInput): AppendSessionEventInput;
+/** Builds the canonical event for an expired task claim. */
+export declare function buildTaskClaimExpiredEventInput(input: BuildTaskClaimExpiredEventInput): AppendSessionEventInput;
+/** Builds the canonical event for a cancelled task. */
+export declare function buildTaskCancelledEventInput(input: BuildTaskCancelledEventInput): AppendSessionEventInput;
+/** Builds the canonical event for a completed task. */
+export declare function buildTaskCompletedEventInput(input: BuildTaskParticipantEventInput): AppendSessionEventInput;
+/** Builds the canonical event for a failed task. */
+export declare function buildTaskFailedEventInput(input: BuildTaskParticipantEventInput): AppendSessionEventInput;
+/** Builds the canonical event for a released task claim. */
+export declare function buildTaskReleasedEventInput(input: BuildTaskParticipantEventInput): AppendSessionEventInput;
+/** Builds the standard progress event published by simple participant workers. */
+export declare function buildTaskProgressEventInput(input: BuildTaskProgressEventInput): AppendSessionEventInput;
+/** Builds the standard output event published by simple participant workers. */
+export declare function buildTaskOutputEventInput(input: BuildTaskOutputEventInput): AppendSessionEventInput;
+/** Extracts a task from a task-created event payload. */
+export declare function taskFromCreatedEvent(event: SessionEvent): TaskRecord | null;
+/** Extracts a task that has become claimable from the public event stream. */
+export declare function taskFromClaimableEvent(event: SessionEvent): TaskRecord | null;
+/** Extracts the cancelled task id from a task cancellation event payload. */
+export declare function taskIdFromCancelledEvent(event: SessionEvent): string | null;
+export {};

package/dist/event-builders.js

@@ -0,0 +1,259 @@
+import { z } from "zod";
+import { sessionEventType, systemProducerId, taskRecordSchema } from "./records.js";
+import { approvalDecisionSchema } from "./rest-schemas.js";
+const sessionEventTypeSchema = z
+    .string()
+    .min(1)
+    .transform((value) => value);
+/** Payload schema for task-created events. */
+export const taskCreatedPayloadSchema = z.object({
+    task: taskRecordSchema,
+});
+/** Payload schema for task-claim-expired events. */
+export const taskClaimExpiredPayloadSchema = z.object({
+    previousClaimedBy: z.string().min(1),
+    task: taskRecordSchema,
+});
+/** Payload schema for task participant lifecycle events that include a task. */
+export const taskParticipantPayloadSchema = z.object({
+    participantId: z.string().min(1),
+    task: taskRecordSchema,
+});
+/** Payload schema for task cancellation events. */
+export const taskCancelledPayloadSchema = z.object({
+    participantId: z.string().min(1),
+    reason: z.record(z.string(), z.unknown()).default({}),
+    task: taskRecordSchema,
+});
+/** Event payload schema for task approval decisions. */
+export const taskApprovalRecordedPayloadSchema = z.object({
+    decision: approvalDecisionSchema,
+    participantId: z.string().min(1),
+    reason: z.record(z.string(), z.unknown()).default({}),
+    task: taskRecordSchema,
+});
+/** Runtime validator for public session events. */
+export const sessionEventSchema = z.object({
+    createdAt: z.string(),
+    eventId: z.string().min(1),
+    payload: z.record(z.string(), z.unknown()),
+    producerId: z.string().min(1),
+    seq: z.number(),
+    sessionId: z.string().min(1),
+    type: sessionEventTypeSchema,
+});
+/** Creates a unique event id in Tether's public event-id namespace. */
+export function newEventId() {
+    return `evt_${newProtocolId()}`;
+}
+/** Creates a participant id scoped by runtime kind for generated REST participants. */
+export function newParticipantId(runtimeKind) {
+    return `part_${runtimeKind}_${newProtocolId()}`;
+}
+/** Creates a unique runtime instance id. */
+export function newParticipantInstanceId() {
+    return `inst_${newProtocolId()}`;
+}
+/** Creates a unique session id. */
+export function newSessionId() {
+    return `sess_${newProtocolId()}`;
+}
+/** Creates a unique task id. */
+export function newTaskId() {
+    return `task_${newProtocolId()}`;
+}
+/** Parses an event replay cursor, falling back to the beginning of the stream. */
+export function parseAfterSeq(value) {
+    return parsePositiveSafeInteger(value) ?? 0;
+}
+/** Parses a positive safe integer without coercing partial decimal strings. */
+export function parsePositiveSafeInteger(value) {
+    if (!value) {
+        return null;
+    }
+    const parsed = Number(value);
+    return Number.isSafeInteger(parsed) && parsed > 0 ? parsed : null;
+}
+/** Builds the durable event for a newly-created session. */
+export function buildSessionCreatedEventInput(sessionId) {
+    return {
+        eventId: newEventId(),
+        payload: {},
+        producerId: systemProducerId,
+        sessionId,
+        type: sessionEventType.sessionCreated,
+    };
+}
+/** Builds a caller-published session event while applying Tether id defaults. */
+export function buildPublishedEventInput(input) {
+    return {
+        eventId: input.eventId ?? newEventId(),
+        payload: input.payload,
+        producerId: input.producerId,
+        sessionId: input.sessionId,
+        type: input.type,
+    };
+}
+/** Builds participant join/update events. */
+export function buildParticipantRegistrationEventInput(input) {
+    if (input.status === "refreshed") {
+        return null;
+    }
+    return {
+        eventId: newEventId(),
+        payload: input.status === "updated"
+            ? {
+                participant: input.participant,
+                previousParticipant: input.previousParticipant,
+            }
+            : { participant: input.participant },
+        producerId: systemProducerId,
+        sessionId: input.sessionId,
+        type: input.status === "joined"
+            ? sessionEventType.participantJoined
+            : sessionEventType.participantUpdated,
+    };
+}
+/** Builds the visible heartbeat event emitted after presence state refreshes. */
+export function buildParticipantHeartbeatEventInput(input) {
+    return {
+        eventId: newEventId(),
+        payload: { participant: input.participant },
+        producerId: systemProducerId,
+        sessionId: input.sessionId,
+        type: sessionEventType.participantHeartbeat,
+    };
+}
+/** Builds the canonical event for a newly-created task. */
+export function buildTaskCreatedEventInput(input) {
+    return {
+        eventId: newEventId(),
+        payload: { task: input.task },
+        producerId: systemProducerId,
+        sessionId: input.sessionId,
+        type: sessionEventType.taskCreated,
+    };
+}
+/** Builds the canonical event for a user or bridge approval decision. */
+export function buildTaskApprovalRecordedEventInput(input) {
+    return {
+        eventId: newEventId(),
+        payload: {
+            decision: input.decision,
+            participantId: input.participantId,
+            reason: input.reason,
+            task: input.task,
+        },
+        producerId: systemProducerId,
+        sessionId: input.sessionId,
+        type: sessionEventType.approvalRecorded,
+    };
+}
+/** Builds the canonical event for a successful task claim. */
+export function buildTaskClaimedEventInput(input) {
+    return buildTaskParticipantEventInput(input, sessionEventType.taskClaimed);
+}
+/** Builds the canonical event for an expired task claim. */
+export function buildTaskClaimExpiredEventInput(input) {
+    return {
+        eventId: newEventId(),
+        payload: { previousClaimedBy: input.previousClaimedBy, task: input.task },
+        producerId: systemProducerId,
+        sessionId: input.sessionId,
+        type: sessionEventType.taskClaimExpired,
+    };
+}
+/** Builds the canonical event for a cancelled task. */
+export function buildTaskCancelledEventInput(input) {
+    return {
+        eventId: newEventId(),
+        payload: {
+            participantId: input.participantId,
+            reason: input.reason,
+            task: input.task,
+        },
+        producerId: systemProducerId,
+        sessionId: input.sessionId,
+        type: sessionEventType.controlCancel,
+    };
+}
+/** Builds the canonical event for a completed task. */
+export function buildTaskCompletedEventInput(input) {
+    return buildTaskParticipantEventInput(input, sessionEventType.taskCompleted);
+}
+/** Builds the canonical event for a failed task. */
+export function buildTaskFailedEventInput(input) {
+    return buildTaskParticipantEventInput(input, sessionEventType.taskFailed);
+}
+/** Builds the canonical event for a released task claim. */
+export function buildTaskReleasedEventInput(input) {
+    return buildTaskParticipantEventInput(input, sessionEventType.taskReleased);
+}
+/** Builds the standard progress event published by simple participant workers. */
+export function buildTaskProgressEventInput(input) {
+    return {
+        eventId: newEventId(),
+        payload: { taskId: input.taskId },
+        producerId: input.participantId,
+        sessionId: input.sessionId,
+        type: sessionEventType.taskProgress,
+    };
+}
+/** Builds the standard output event published by simple participant workers. */
+export function buildTaskOutputEventInput(input) {
+    return {
+        eventId: newEventId(),
+        payload: { output: input.output, taskId: input.taskId },
+        producerId: input.participantId,
+        sessionId: input.sessionId,
+        type: sessionEventType.agentOutput,
+    };
+}
+/** Extracts a task from a task-created event payload. */
+export function taskFromCreatedEvent(event) {
+    if (event.type !== sessionEventType.taskCreated) {
+        return null;
+    }
+    const parsed = taskCreatedPayloadSchema.safeParse(event.payload);
+    return parsed.success ? parsed.data.task : null;
+}
+/** Extracts a task that has become claimable from the public event stream. */
+export function taskFromClaimableEvent(event) {
+    if (event.type === sessionEventType.taskCreated) {
+        return taskFromCreatedEvent(event);
+    }
+    if (event.type === sessionEventType.taskClaimExpired) {
+        const parsed = taskClaimExpiredPayloadSchema.safeParse(event.payload);
+        return parsed.success ? parsed.data.task : null;
+    }
+    if (event.type !== sessionEventType.taskReleased) {
+        return null;
+    }
+    const parsed = taskParticipantPayloadSchema.safeParse(event.payload);
+    return parsed.success ? parsed.data.task : null;
+}
+/** Extracts the cancelled task id from a task cancellation event payload. */
+export function taskIdFromCancelledEvent(event) {
+    if (event.type !== sessionEventType.controlCancel) {
+        return null;
+    }
+    const parsed = taskCancelledPayloadSchema.safeParse(event.payload);
+    return parsed.success ? parsed.data.task.taskId : null;
+}
+function buildTaskParticipantEventInput(input, type) {
+    return {
+        eventId: newEventId(),
+        payload: { participantId: input.participantId, task: input.task },
+        producerId: systemProducerId,
+        sessionId: input.sessionId,
+        type,
+    };
+}
+function newProtocolId() {
+    const randomUuid = readGlobalRandomUuid();
+    return randomUuid ?? `${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 12)}`;
+}
+function readGlobalRandomUuid() {
+    const candidate = globalThis;
+    return candidate.crypto?.randomUUID?.() ?? null;
+}

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export * from "./event-builders.js";
+export * from "./records.js";
+export * from "./rest-schemas.js";
+export * from "./task-contracts.js";
+export * from "./task-payload-display.js";
+export * from "./websocket.js";

package/dist/index.js

@@ -0,0 +1,6 @@
+export * from "./event-builders.js";
+export * from "./records.js";
+export * from "./rest-schemas.js";
+export * from "./task-contracts.js";
+export * from "./task-payload-display.js";
+export * from "./websocket.js";