@dungle-scrubs/tether-protocol 0.1.0

package/dist/records.d.ts

@@ -0,0 +1,313 @@
+import { z } from "zod";
+import type { CandidateScheduleIdentity } from "./task-contracts.js";
+/**
+ * Durable task record returned by Tether task APIs and embedded in task
+ * lifecycle events.
+ */
+export interface TaskRecord {
+    /** Cancellation timestamp, when the task has been cancelled. */
+    readonly cancelledAt: string | null;
+    /** Claim-expiration timestamp persisted after the scheduler clears an elapsed claim. */
+    readonly claimExpiredAt: string | null;
+    /** Participant id whose claim elapsed, when the scheduler cleared it. */
+    readonly claimExpiredBy: string | null;
+    /** Claim lease expiry timestamp, when a claimed task should become claimable again. */
+    readonly claimExpiresAt: string | null;
+    /** Claim timestamp, when a participant runtime currently owns the task. */
+    readonly claimedAt: string | null;
+    /** Participant id currently claiming the task. */
+    readonly claimedBy: string | null;
+    /** Completion timestamp, when the task has completed successfully. */
+    readonly completedAt: string | null;
+    /** Creation timestamp returned by Tether. */
+    readonly createdAt: string;
+    /** Failure timestamp, when the task has reached a terminal failure. */
+    readonly failedAt: string | null;
+    /** Structured failure payload, when the task failed with details. */
+    readonly failure: Record<string, unknown> | null;
+    /** Structured task input supplied at creation time, when available. */
+    readonly input: Record<string, unknown> | null;
+    /** Task kind used by participant runtimes to decide claimability. */
+    readonly kind: string;
+    /** User-visible task objective. */
+    readonly objective: string;
+    /** Last claim release timestamp, when a participant explicitly released the task. */
+    readonly releasedAt: string | null;
+    /** Participant id that explicitly released the task claim. */
+    readonly releasedBy: string | null;
+    /** Structured result payload, when the task completed with details. */
+    readonly result: Record<string, unknown> | null;
+    /**
+     * Deterministic schedule and Mailbox Scope identity for scheduled maintenance
+     * runs; null for manual tasks. Present only when the durable row carries a
+     * complete Schedule Window and Mailbox Scope.
+     */
+    readonly schedule?: CandidateScheduleIdentity | null;
+    /** Durable Tether session that owns the task. */
+    readonly sessionId: string;
+    /** Durable task id. */
+    readonly taskId: string;
+}
+/** Public session event type names used by REST and WebSocket boundaries. */
+export type SessionEventType = "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 & {});
+/** Runtime kind advertised by a participant. */
+export type ParticipantRuntimeKind = "claude_code" | "codex" | "generic_agent" | "openai_agent" | "pi_coding_agent" | (string & {});
+/** Control channel used by a participant runtime. */
+export type ControlChannel = "rest" | "ws";
+/** Durable event visible in one Tether session stream. */
+export interface SessionEvent {
+    readonly createdAt: string;
+    readonly eventId: string;
+    readonly payload: Record<string, unknown>;
+    readonly producerId: string;
+    readonly seq: number;
+    readonly sessionId: string;
+    readonly type: SessionEventType;
+}
+/** Visible participant presence record. */
+export interface ParticipantRecord {
+    readonly capabilities: Record<string, unknown>;
+    readonly displayName: string;
+    readonly joinedAt: string;
+    readonly lastSeenAt: string;
+    readonly participantId: string;
+    readonly runtimeKind: ParticipantRuntimeKind;
+    readonly sessionId: string;
+}
+/**
+ * Task lifecycle filter for user-facing task lists.
+ */
+export type TaskListStatus = "active" | "all" | "terminal";
+/** Durable Tether session row shared by service and adapter diagnostics. */
+export interface SessionRecord {
+    /** Time this session was first created. */
+    readonly createdAt: string;
+    /** Durable session identifier. */
+    readonly sessionId: string;
+}
+/**
+ * Durable association between an external client conversation and one Tether
+ * session.
+ */
+export interface ClientSessionBindingRecord {
+    /** Time this binding was archived, or null while active. */
+    readonly archivedAt: string | null;
+    /** Time this binding was first created. */
+    readonly createdAt: string;
+    /** Provider-specific conversation id, such as an external chat id. */
+    readonly externalId: string;
+    /** Most recent time a bridge resolved this binding. */
+    readonly lastSeenAt: string;
+    /** Client integration provider, such as `external-chat` or `slack`. */
+    readonly provider: string;
+    /** Durable Tether session associated with the external conversation. */
+    readonly sessionId: string;
+}
+/** Operator-facing state derived from the durable participant control lease. */
+export type ControlLeaseStatus = "active" | "expired" | "released" | "superseded";
+/** Read-only diagnostic view of one participant control lease. */
+export interface ControlLeaseSnapshot {
+    /** When this runtime instance first claimed the participant control channel. */
+    readonly claimedAt: string;
+    /** Whether this runtime instance controls the participant through REST or WebSocket. */
+    readonly controlChannel: ControlChannel;
+    /** Immutable, strictly-monotonic server-issued Control Epoch for this lease. */
+    readonly epoch: number;
+    /** Concrete runtime process currently or formerly associated with the lease. */
+    readonly instanceId: string;
+    /** Most recent durable refresh observed for this lease. */
+    readonly lastSeenAt: string;
+    /** Time after which an unreleased lease no longer blocks another runtime. */
+    readonly leaseExpiresAt: string;
+    /** Participant identity controlled by this runtime instance. */
+    readonly participantId: string;
+    /** Time this lease was explicitly released, or null while unreleased. */
+    readonly releasedAt: string | null;
+    /** Session that owns this participant control lease. */
+    readonly sessionId: string;
+    /** Time this lease was superseded by another runtime, or null while current. */
+    readonly supersededAt: string | null;
+    /** Current derived lease state for operator diagnostics. */
+    readonly status: ControlLeaseStatus;
+}
+/** Operator-facing state derived from a durable task row. */
+export type TaskSnapshotStatus = "cancelled" | "claim_active" | "claim_cleared" | "claim_expired" | "completed" | "failed" | "unclaimed";
+/** Durable approval decision attached to one task target. */
+export interface TaskApprovalRecord {
+    /** Event id of the corresponding `approval.recorded` event. */
+    readonly approvalEventId: string;
+    /** Time the winning approval decision was committed. */
+    readonly decidedAt: string;
+    /** Participant that issued the winning decision. */
+    readonly decidedByParticipantId: string;
+    /** Winning approval decision for the target. */
+    readonly decision: "approved" | "rejected";
+    /** Original approval reason used to derive the target key. */
+    readonly reason: Record<string, unknown>;
+    /** Session that owns the task. */
+    readonly sessionId: string;
+    /** Canonical durable approval target key. */
+    readonly targetKey: string;
+    /** Approved task id. */
+    readonly taskId: string;
+}
+/** Read-only diagnostic view of one task with derived lifecycle state. */
+export interface TaskSnapshot extends TaskRecord {
+    /** Schema-backed approval decisions recorded for this task. */
+    readonly approvals: readonly TaskApprovalRecord[];
+    /** Current derived task state for operator diagnostics. */
+    readonly status: TaskSnapshotStatus;
+}
+/**
+ * Operator-facing state derived from visible participant presence and control
+ * lease state.
+ */
+export type ParticipantRuntimeSnapshotStatus = "lease_without_presence" | "registered_control_active" | "registered_control_inactive" | "registered_without_control";
+/**
+ * Read-only diagnostic view of a participant identity and the runtime instance
+ * that currently or most recently controlled it.
+ */
+export interface ParticipantRuntimeSnapshot {
+    /** Number of durable control-lease rows associated with this participant. */
+    readonly controlLeaseCount: number;
+    /** Active control lease for this participant, or null when no runtime currently controls it. */
+    readonly currentControlLease: ControlLeaseSnapshot | null;
+    /** Most recently observed control lease for this participant, including inactive leases. */
+    readonly latestControlLease: ControlLeaseSnapshot | null;
+    /** Visible participant presence record, or null when only lease state exists. */
+    readonly participant: ParticipantRecord | null;
+    /** Participant identity being diagnosed. */
+    readonly participantId: string;
+    /** Whether this participant has visible presence in the session. */
+    readonly registered: boolean;
+    /** Session that owns the participant runtime state. */
+    readonly sessionId: string;
+    /** Current derived participant runtime state for operator diagnostics. */
+    readonly status: ParticipantRuntimeSnapshotStatus;
+}
+/** Participant counts in a session debug summary. */
+export interface SessionDebugParticipantSummary {
+    /** Number of visible participant identities with an active control lease. */
+    readonly activeControl: number;
+    /** Number of participant identities represented only by lease state. */
+    readonly leaseOnly: number;
+    /** Number of visible participant identities. */
+    readonly registered: number;
+    /** Number of participant runtime snapshots in the summary. */
+    readonly total: number;
+    /** Number of visible participant identities without active control. */
+    readonly withoutActiveControl: number;
+}
+/** Control lease counts in a session debug summary. */
+export interface SessionDebugControlLeaseSummary {
+    /** Number of unreleased control leases whose lease time has not elapsed. */
+    readonly active: number;
+    /** Number of unreleased control leases whose lease time has elapsed. */
+    readonly expired: number;
+    /** Number of explicitly released control leases. */
+    readonly released: number;
+    /** Number of control leases superseded by a later owner. */
+    readonly superseded: number;
+    /** Number of control lease snapshots in the summary. */
+    readonly total: number;
+}
+/** Task counts in a session debug summary. */
+export interface SessionDebugTaskSummary {
+    /** Number of currently active task claims. */
+    readonly activeClaims: number;
+    /** Number of cancelled tasks. */
+    readonly cancelled: number;
+    /** Number of tasks that can be claimed without waiting for the scheduler. */
+    readonly claimable: number;
+    /** Number of active claim snapshots. */
+    readonly claimActive: number;
+    /** Number of cleared claim snapshots. */
+    readonly claimCleared: number;
+    /** Number of expired claim snapshots waiting for scheduler cleanup. */
+    readonly claimExpired: number;
+    /** Number of completed tasks. */
+    readonly completed: number;
+    /** Number of expired task claims waiting for scheduler cleanup. */
+    readonly expiredClaims: number;
+    /** Number of failed tasks. */
+    readonly failed: number;
+    /** Number of terminal tasks. */
+    readonly terminal: number;
+    /** Number of task snapshots in the summary. */
+    readonly total: number;
+    /** Number of unclaimed tasks. */
+    readonly unclaimed: number;
+}
+/** Read-only aggregate diagnostic view for one session. */
+export interface SessionDebugSummary {
+    /** Participant runtime snapshot counts. */
+    readonly participants: SessionDebugParticipantSummary;
+    /** Control lease snapshot counts. */
+    readonly controlLeases: SessionDebugControlLeaseSummary;
+    /** Session being summarized. */
+    readonly sessionId: string;
+    /** Task snapshot counts. */
+    readonly tasks: SessionDebugTaskSummary;
+}
+/** Producer id used by Tether-owned system events. */
+export declare const systemProducerId = "tether";
+/** Canonical session event names. */
+export declare const sessionEventType: {
+    readonly agentOutput: "agent.output";
+    readonly approvalRecorded: "approval.recorded";
+    readonly controlCancel: "control.cancel";
+    readonly participantHeartbeat: "participant.heartbeat";
+    readonly participantJoined: "participant.joined";
+    readonly participantUpdated: "participant.updated";
+    readonly sessionCreated: "session.created";
+    readonly taskClaimExpired: "task.claim_expired";
+    readonly taskClaimed: "task.claimed";
+    readonly taskCompleted: "task.completed";
+    readonly taskCreated: "task.created";
+    readonly taskFailed: "task.failed";
+    readonly taskProgress: "task.progress";
+    readonly taskReleased: "task.released";
+    readonly userMessage: "user.message";
+};
+/** Canonical WebSocket operation names. */
+export declare const webSocketOperation: {
+    readonly commandResult: "command.result";
+    readonly error: "error";
+    readonly event: "event";
+    readonly publish: "publish";
+    readonly replayComplete: "replay.complete";
+    readonly taskCancel: "task.cancel";
+    readonly taskClaim: "task.claim";
+    readonly taskComplete: "task.complete";
+    readonly taskFail: "task.fail";
+    readonly taskRefresh: "task.refresh";
+    readonly taskRelease: "task.release";
+};
+/**
+ * Runtime validator for durable task records crossing REST and WebSocket
+ * protocol boundaries.
+ */
+export declare const taskRecordSchema: 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>;
+/** Runtime validator for participant control channels. */
+export declare const controlChannelSchema: z.ZodUnion<readonly [z.ZodLiteral<"rest">, z.ZodLiteral<"ws">]>;
+/** Runtime validator for participant runtime kinds. */
+export declare const participantRuntimeKindSchema: z.ZodDefault<z.ZodUnion<readonly [z.ZodLiteral<"claude_code">, z.ZodLiteral<"codex">, z.ZodLiteral<"generic_agent">, z.ZodLiteral<"openai_agent">, z.ZodLiteral<"pi_coding_agent">, z.ZodString]>>;

package/dist/records.js

@@ -0,0 +1,72 @@
+import { z } from "zod";
+/** Producer id used by Tether-owned system events. */
+export const systemProducerId = "tether";
+/** Canonical session event names. */
+export const sessionEventType = {
+    agentOutput: "agent.output",
+    approvalRecorded: "approval.recorded",
+    controlCancel: "control.cancel",
+    participantHeartbeat: "participant.heartbeat",
+    participantJoined: "participant.joined",
+    participantUpdated: "participant.updated",
+    sessionCreated: "session.created",
+    taskClaimExpired: "task.claim_expired",
+    taskClaimed: "task.claimed",
+    taskCompleted: "task.completed",
+    taskCreated: "task.created",
+    taskFailed: "task.failed",
+    taskProgress: "task.progress",
+    taskReleased: "task.released",
+    userMessage: "user.message",
+};
+/** Canonical WebSocket operation names. */
+export const webSocketOperation = {
+    commandResult: "command.result",
+    error: "error",
+    event: "event",
+    publish: "publish",
+    replayComplete: "replay.complete",
+    taskCancel: "task.cancel",
+    taskClaim: "task.claim",
+    taskComplete: "task.complete",
+    taskFail: "task.fail",
+    taskRefresh: "task.refresh",
+    taskRelease: "task.release",
+};
+/**
+ * Runtime validator for durable task records crossing REST and WebSocket
+ * protocol boundaries.
+ */
+export const taskRecordSchema = z.object({
+    cancelledAt: z.string().nullable(),
+    claimExpiredAt: z.string().nullable(),
+    claimExpiredBy: z.string().nullable(),
+    claimExpiresAt: z.string().nullable(),
+    claimedAt: z.string().nullable(),
+    claimedBy: z.string().nullable(),
+    completedAt: z.string().nullable(),
+    createdAt: z.string(),
+    failedAt: z.string().nullable(),
+    failure: z.record(z.string(), z.unknown()).nullable(),
+    input: z.record(z.string(), z.unknown()).nullable(),
+    kind: z.string().min(1),
+    objective: z.string().min(1),
+    releasedAt: z.string().nullable(),
+    releasedBy: z.string().nullable(),
+    result: z.record(z.string(), z.unknown()).nullable(),
+    sessionId: z.string().min(1),
+    taskId: z.string().min(1),
+});
+/** Runtime validator for participant control channels. */
+export const controlChannelSchema = z.union([z.literal("rest"), z.literal("ws")]);
+/** Runtime validator for participant runtime kinds. */
+export const participantRuntimeKindSchema = z
+    .union([
+    z.literal("claude_code"),
+    z.literal("codex"),
+    z.literal("generic_agent"),
+    z.literal("openai_agent"),
+    z.literal("pi_coding_agent"),
+    z.string().min(1),
+])
+    .default("generic_agent");

package/dist/rest-schemas.d.ts

@@ -0,0 +1,149 @@
+import { z } from "zod";
+/**
+ * Server-issued Control Epoch carried by control-protected REST requests. It is
+ * a positive safe integer; the server validates it against the current durable
+ * lease generation in the same transaction as the protected mutation.
+ */
+export declare const controlEpochSchema: z.ZodNumber;
+/** Pagination metadata returned by bounded session event-list responses. */
+export declare const eventListPaginationSchema: z.ZodObject<{
+    afterSeq: z.ZodNumber;
+    hasMore: z.ZodBoolean;
+    limit: z.ZodNumber;
+    nextAfterSeq: z.ZodNumber;
+    returned: z.ZodNumber;
+}, z.core.$strip>;
+/** HTTP response schema for bounded session event-list responses. */
+export declare const eventListResponseSchema: z.ZodObject<{
+    events: z.ZodArray<z.ZodLazy<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>>>;
+    pagination: z.ZodObject<{
+        afterSeq: z.ZodNumber;
+        hasMore: z.ZodBoolean;
+        limit: z.ZodNumber;
+        nextAfterSeq: z.ZodNumber;
+        returned: z.ZodNumber;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+/** Pagination metadata returned by bounded session event-list responses. */
+export type EventListPagination = z.infer<typeof eventListPaginationSchema>;
+/** HTTP response body for bounded session event-list responses. */
+export type EventListResponse = z.infer<typeof eventListResponseSchema>;
+/** HTTP body schema for appending a generic session event. */
+export declare const appendEventSchema: z.ZodObject<{
+    controlEpoch: z.ZodOptional<z.ZodNumber>;
+    eventId: z.ZodOptional<z.ZodString>;
+    instanceId: z.ZodOptional<z.ZodString>;
+    payload: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    producerId: z.ZodString;
+    type: z.ZodString;
+}, z.core.$strip>;
+/** HTTP body schema for session creation. */
+export declare const createSessionSchema: z.ZodObject<{
+    sessionId: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+/** HTTP body schema for resolving external client conversations. */
+export declare const resolveClientSessionSchema: z.ZodObject<{
+    externalId: z.ZodString;
+    provider: z.ZodString;
+    sessionId: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+/** HTTP body schema for participant registration. */
+export declare const registerParticipantSchema: z.ZodObject<{
+    capabilities: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    controlChannel: z.ZodDefault<z.ZodUnion<readonly [z.ZodLiteral<"rest">, z.ZodLiteral<"ws">]>>;
+    displayName: z.ZodOptional<z.ZodString>;
+    instanceId: z.ZodOptional<z.ZodString>;
+    participantId: z.ZodOptional<z.ZodString>;
+    runtimeKind: z.ZodDefault<z.ZodUnion<readonly [z.ZodLiteral<"claude_code">, z.ZodLiteral<"codex">, z.ZodLiteral<"generic_agent">, z.ZodLiteral<"openai_agent">, z.ZodLiteral<"pi_coding_agent">, z.ZodString]>>;
+}, z.core.$strip>;
+/** HTTP body schema for participant heartbeat refresh. */
+export declare const heartbeatParticipantSchema: z.ZodObject<{
+    capabilities: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    controlEpoch: z.ZodOptional<z.ZodNumber>;
+    instanceId: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+/** HTTP body schema for task creation. */
+/**
+ * Deterministic schedule and Mailbox Scope identity a scheduled maintenance run
+ * carries at creation. Interval and algorithm version are part of task identity.
+ */
+export declare const scheduledTaskIdentitySchema: z.ZodObject<{
+    mailboxAccountId: z.ZodString;
+    mailboxProvider: z.ZodString;
+    scheduleAlgorithmVersion: z.ZodNumber;
+    scheduleIntervalMs: z.ZodNumber;
+    scheduleWindowStart: z.ZodNumber;
+}, z.core.$strip>;
+export declare const createTaskSchema: z.ZodObject<{
+    input: z.ZodOptional<z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+    kind: z.ZodString;
+    objective: z.ZodString;
+    requireContract: z.ZodOptional<z.ZodBoolean>;
+    schedule: z.ZodOptional<z.ZodObject<{
+        mailboxAccountId: z.ZodString;
+        mailboxProvider: z.ZodString;
+        scheduleAlgorithmVersion: z.ZodNumber;
+        scheduleIntervalMs: z.ZodNumber;
+        scheduleWindowStart: z.ZodNumber;
+    }, z.core.$strip>>;
+    taskId: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+/** HTTP body schema for task claim. */
+export declare const claimTaskSchema: z.ZodObject<{
+    controlEpoch: z.ZodOptional<z.ZodNumber>;
+    instanceId: z.ZodOptional<z.ZodString>;
+    participantId: z.ZodString;
+}, z.core.$strip>;
+/** HTTP body schema for task claim refresh. */
+export declare const refreshTaskClaimSchema: z.ZodObject<{
+    controlEpoch: z.ZodOptional<z.ZodNumber>;
+    instanceId: z.ZodOptional<z.ZodString>;
+    participantId: z.ZodString;
+}, z.core.$strip>;
+/** HTTP body schema for task cancellation. */
+export declare const cancelTaskSchema: z.ZodObject<{
+    controlEpoch: z.ZodOptional<z.ZodNumber>;
+    instanceId: z.ZodOptional<z.ZodString>;
+    participantId: z.ZodString;
+    reason: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strip>;
+/** HTTP body schema for task completion. */
+export declare const completeTaskSchema: z.ZodObject<{
+    controlEpoch: z.ZodOptional<z.ZodNumber>;
+    instanceId: z.ZodOptional<z.ZodString>;
+    participantId: z.ZodString;
+    result: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strip>;
+/** HTTP body schema for task failure. */
+export declare const failTaskSchema: z.ZodObject<{
+    controlEpoch: z.ZodOptional<z.ZodNumber>;
+    failure: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    instanceId: z.ZodOptional<z.ZodString>;
+    participantId: z.ZodString;
+}, z.core.$strip>;
+/** HTTP body schema for task claim release. */
+export declare const releaseTaskSchema: z.ZodObject<{
+    controlEpoch: z.ZodOptional<z.ZodNumber>;
+    instanceId: z.ZodOptional<z.ZodString>;
+    participantId: z.ZodString;
+}, z.core.$strip>;
+/** Schema for durable task approval decisions. */
+export declare const approvalDecisionSchema: z.ZodUnion<readonly [z.ZodLiteral<"approved">, z.ZodLiteral<"rejected">]>;
+/** Durable approval decision values recorded in session events. */
+export type ApprovalDecision = z.infer<typeof approvalDecisionSchema>;
+/** HTTP payload schema for recording approval intent for a task. */
+export declare const recordTaskApprovalSchema: z.ZodObject<{
+    controlEpoch: z.ZodOptional<z.ZodNumber>;
+    decision: z.ZodUnion<readonly [z.ZodLiteral<"approved">, z.ZodLiteral<"rejected">]>;
+    instanceId: z.ZodOptional<z.ZodString>;
+    participantId: z.ZodString;
+    reason: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strip>;

package/dist/rest-schemas.js

@@ -0,0 +1,131 @@
+import { z } from "zod";
+import { sessionEventSchema } from "./event-builders.js";
+import { controlChannelSchema, participantRuntimeKindSchema } from "./records.js";
+/**
+ * Server-issued Control Epoch carried by control-protected REST requests. It is
+ * a positive safe integer; the server validates it against the current durable
+ * lease generation in the same transaction as the protected mutation.
+ */
+export const controlEpochSchema = z
+    .number()
+    .int()
+    .positive()
+    .refine((value) => Number.isSafeInteger(value), {
+    message: "controlEpoch must be a positive safe integer",
+});
+/** Pagination metadata returned by bounded session event-list responses. */
+export const eventListPaginationSchema = z.object({
+    afterSeq: z.number().int().nonnegative(),
+    hasMore: z.boolean(),
+    limit: z.number().int().positive(),
+    nextAfterSeq: z.number().int().nonnegative(),
+    returned: z.number().int().nonnegative(),
+});
+/** HTTP response schema for bounded session event-list responses. */
+export const eventListResponseSchema = z.object({
+    events: z.array(z.lazy(() => sessionEventSchema)),
+    pagination: eventListPaginationSchema,
+});
+/** HTTP body schema for appending a generic session event. */
+export const appendEventSchema = z.object({
+    controlEpoch: controlEpochSchema.optional(),
+    eventId: z.string().min(1).optional(),
+    instanceId: z.string().min(1).optional(),
+    payload: z.record(z.string(), z.unknown()).default({}),
+    producerId: z.string().min(1),
+    type: z.string().min(1),
+});
+/** HTTP body schema for session creation. */
+export const createSessionSchema = z.object({
+    sessionId: z.string().min(1).optional(),
+});
+/** HTTP body schema for resolving external client conversations. */
+export const resolveClientSessionSchema = z.object({
+    externalId: z.string().min(1),
+    provider: z.string().min(1),
+    sessionId: z.string().min(1).optional(),
+});
+/** HTTP body schema for participant registration. */
+export const registerParticipantSchema = z.object({
+    capabilities: z.record(z.string(), z.unknown()).default({}),
+    controlChannel: controlChannelSchema.default("rest"),
+    displayName: z.string().min(1).optional(),
+    instanceId: z.string().min(1).optional(),
+    participantId: z.string().min(1).optional(),
+    runtimeKind: participantRuntimeKindSchema,
+});
+/** HTTP body schema for participant heartbeat refresh. */
+export const heartbeatParticipantSchema = z.object({
+    capabilities: z.record(z.string(), z.unknown()).optional(),
+    controlEpoch: controlEpochSchema.optional(),
+    instanceId: z.string().min(1).optional(),
+});
+/** HTTP body schema for task creation. */
+/**
+ * Deterministic schedule and Mailbox Scope identity a scheduled maintenance run
+ * carries at creation. Interval and algorithm version are part of task identity.
+ */
+export const scheduledTaskIdentitySchema = z.object({
+    mailboxAccountId: z.string().min(1),
+    mailboxProvider: z.string().min(1),
+    scheduleAlgorithmVersion: z.number().int().positive(),
+    scheduleIntervalMs: z.number().int().positive(),
+    scheduleWindowStart: z.number().int().nonnegative(),
+});
+export const createTaskSchema = z.object({
+    input: z.record(z.string(), z.unknown()).nullable().optional(),
+    kind: z.string().min(1),
+    objective: z.string().min(1),
+    requireContract: z.boolean().optional(),
+    schedule: scheduledTaskIdentitySchema.optional(),
+    taskId: z.string().min(1).optional(),
+});
+/** HTTP body schema for task claim. */
+export const claimTaskSchema = z.object({
+    controlEpoch: controlEpochSchema.optional(),
+    instanceId: z.string().min(1).optional(),
+    participantId: z.string().min(1),
+});
+/** HTTP body schema for task claim refresh. */
+export const refreshTaskClaimSchema = z.object({
+    controlEpoch: controlEpochSchema.optional(),
+    instanceId: z.string().min(1).optional(),
+    participantId: z.string().min(1),
+});
+/** HTTP body schema for task cancellation. */
+export const cancelTaskSchema = z.object({
+    controlEpoch: controlEpochSchema.optional(),
+    instanceId: z.string().min(1).optional(),
+    participantId: z.string().min(1),
+    reason: z.record(z.string(), z.unknown()).default({}),
+});
+/** HTTP body schema for task completion. */
+export const completeTaskSchema = z.object({
+    controlEpoch: controlEpochSchema.optional(),
+    instanceId: z.string().min(1).optional(),
+    participantId: z.string().min(1),
+    result: z.record(z.string(), z.unknown()).default({}),
+});
+/** HTTP body schema for task failure. */
+export const failTaskSchema = z.object({
+    controlEpoch: controlEpochSchema.optional(),
+    failure: z.record(z.string(), z.unknown()).default({}),
+    instanceId: z.string().min(1).optional(),
+    participantId: z.string().min(1),
+});
+/** HTTP body schema for task claim release. */
+export const releaseTaskSchema = z.object({
+    controlEpoch: controlEpochSchema.optional(),
+    instanceId: z.string().min(1).optional(),
+    participantId: z.string().min(1),
+});
+/** Schema for durable task approval decisions. */
+export const approvalDecisionSchema = z.union([z.literal("approved"), z.literal("rejected")]);
+/** HTTP payload schema for recording approval intent for a task. */
+export const recordTaskApprovalSchema = z.object({
+    controlEpoch: controlEpochSchema.optional(),
+    decision: approvalDecisionSchema,
+    instanceId: z.string().min(1).optional(),
+    participantId: z.string().min(1),
+    reason: z.record(z.string(), z.unknown()).default({}),
+});