@theowlops/boombot 0.0.0-stage → 1.1.0

package/dist/node_modules/@boombot/protocol/gateway-protocol/commands.js

@@ -0,0 +1,563 @@
+import { z } from "zod";
+import { EXTRA_COMMAND_DEFS as CHANNEL_EXTRA_COMMAND_DEFS } from "./commands-channels.js";
+import { EXTRA_COMMAND_DEFS as SCHEDULER_EXTRA_COMMAND_DEFS } from "./commands-scheduler.js";
+import { ProtocolError } from "./errors.js";
+/**
+ * Typed command schemas for every command the web UI (phase 1) needs.
+ *
+ * Each command definition carries a literal `type`, a zod `payload` schema
+ * (what the client sends inside the envelope) and a zod `response` schema
+ * (what the gateway returns inside the response envelope).
+ *
+ * Wire-evolution rule (additive-first): payloads and responses only ever gain
+ * OPTIONAL fields. Unknown fields are stripped, never rejected, so a newer
+ * server can talk to an older client within the same wire version.
+ */
+// ---------------------------------------------------------------------------
+// Shared shapes
+// ---------------------------------------------------------------------------
+/**
+ * Provider kind on the wire. Accepts any non-empty string — the gateway's
+ * provider service validates it against the live profile registry (built-ins
+ * plus user-defined custom providers from `custom-providers.json`), so the
+ * wire schema stays permissive while the service stays strict.
+ */
+export const providerKindSchema = z.string().min(1);
+/** Per-model reasoning knobs. Each wire protocol maps them its own way. */
+export const reasoningProfileSchema = z.object({
+    /** OpenAI-style reasoning effort (sent as `reasoning_effort` on OpenAI-compatible kinds). */
+    effort: z.string().min(1).optional(),
+    /** Anthropic-style thinking budget in tokens (sent as `thinking.budget_tokens`). */
+    budgetTokens: z.number().int().positive().optional(),
+});
+/**
+ * Request profile: per-request overrides merged in three tiers —
+ * kind defaults < provider.extra < per-model override. Stored in
+ * providers.json, applied by the gateway when building provider requests.
+ */
+export const requestProfileSchema = z.object({
+    maxTokens: z.number().int().positive().optional(),
+    temperature: z.number().min(0).optional(),
+    topP: z.number().min(0).max(1).optional(),
+    /** Extra HTTP headers merged over (but never overriding) the auth headers. */
+    headers: z.record(z.string(), z.string()).optional(),
+    /** Extra top-level fields merged into the JSON request body. */
+    extraBody: z.record(z.string(), z.unknown()).optional(),
+    reasoning: reasoningProfileSchema.optional(),
+});
+export const providerSchema = z.object({
+    id: z.string().min(1),
+    name: z.string().min(1),
+    kind: providerKindSchema,
+    baseUrl: z.string().url().optional(),
+    hasKey: z.boolean(),
+    /** Number of API keys in the provider's KeyRoulette ring. */
+    keyCount: z.number().int().nonnegative(),
+    /** Key-rotation cursor: index of the ring entry tried first (operational state). */
+    keyCursor: z.number().int().nonnegative().optional(),
+    active: z.boolean(),
+    /** Default chat model for turns. Never overwritten by probe discovery. */
+    model: z.string().min(1).optional(),
+    models: z.array(z.string()).optional(),
+    /** Provider-level request profile (tier 2 of 3). */
+    extra: requestProfileSchema.optional(),
+    /** Per-model request profile overrides (tier 3 of 3), keyed by model id. */
+    modelProfiles: z.record(z.string(), requestProfileSchema).optional(),
+});
+/** Provider record as sent by the client on `provider.save`. `apiKey`/`apiKeys` are write-only and never echoed back. */
+export const providerInputSchema = providerSchema
+    .omit({ hasKey: true, active: true, keyCount: true, keyCursor: true })
+    .extend({
+    hasKey: z.boolean().optional(),
+    /** Server default when omitted. */
+    active: z.boolean().optional(),
+    apiKey: z.string().min(1).optional(),
+    /**
+     * Replace the whole key ring. Mutually exclusive with `apiKey`;
+     * omitted = keep stored keys, `[]` = clear.
+     */
+    apiKeys: z.array(z.string().min(1)).max(32).optional(),
+});
+export const sessionConfigSnapshotSchema = z.object({
+    model: z.string().min(1).optional(),
+    provider: z.string().min(1).optional(),
+    toolsEnabled: z.number().int().nonnegative(),
+    systemPromptHash: z.string().min(1),
+});
+export const sessionSchema = z.object({
+    id: z.string().min(1),
+    title: z.string(),
+    createdAt: z.string(),
+    updatedAt: z.string(),
+    messageCount: z.number().int().nonnegative(),
+    /** P1-7: point-in-time config serving the session's turns; absent until the first turn. */
+    configSnapshot: sessionConfigSnapshotSchema.optional(),
+});
+export const messageSchema = z.object({
+    id: z.string().min(1),
+    role: z.enum(["user", "assistant", "system", "tool"]),
+    content: z.string(),
+    createdAt: z.string(),
+    toolCallId: z.string().optional(),
+    toolName: z.string().optional(),
+    /** P1-6: context checkpoint flag — prompt projection starts here. */
+    isCheckpoint: z.boolean().optional(),
+    /**
+     * P2-3: active variant index the read resolved to. Present and > 0 when a
+     * variant's content is shown; absent means the base row's content.
+     */
+    variantIndex: z.number().int().nonnegative().optional(),
+});
+/** P2-3: one alternate content stored at a message position. */
+export const variantSchema = z.object({
+    id: z.string().min(1),
+    sessionId: z.string().min(1),
+    messageId: z.string().min(1),
+    variantIndex: z.number().int().positive(),
+    content: z.string(),
+    createdAt: z.string(),
+});
+export const scheduleSchema = z.object({
+    id: z.string().min(1),
+    name: z.string().min(1),
+    cron: z.string().min(1),
+    prompt: z.string().min(1),
+    enabled: z.boolean(),
+    nextRunAt: z.string().optional(),
+});
+export const memoryHitSchema = z.object({
+    id: z.string().min(1),
+    excerpt: z.string(),
+    score: z.number(),
+});
+export const channelSchema = z.object({
+    id: z.string().min(1),
+    kind: z.string().min(1),
+    status: z.enum(["connected", "disconnected", "error", "pending"]),
+    displayName: z.string(),
+});
+export const attachmentSchema = z.object({
+    id: z.string().min(1),
+    name: z.string(),
+    mimeType: z.string(),
+    sizeBytes: z.number().int().nonnegative(),
+    ref: z.string(),
+});
+export const turnStatusSchema = z.enum([
+    "queued",
+    "running",
+    "completed",
+    "cancelled",
+    "failed",
+]);
+const okSchema = z.object({ ok: z.boolean() });
+// ---------------------------------------------------------------------------
+// Background task runner (wire v1 additive).
+//
+// Schemas for long-running background tasks (`task.*` commands below).
+// Additive-first: these only add new command/event types; no existing field
+// or schema is touched, so older wire v1 clients keep working unchanged.
+// ---------------------------------------------------------------------------
+export const taskStatusSchema = z.enum([
+    "queued",
+    "running",
+    "paused",
+    "awaiting_approval",
+    "completed",
+    "failed",
+    "cancelled",
+    "interrupted",
+]);
+export const taskStepSchema = z.object({
+    id: z.string().min(1),
+    index: z.number().int().nonnegative(),
+    kind: z.literal("turn"),
+    prompt: z.string().min(1),
+    status: z.enum(["pending", "running", "done", "failed", "skipped"]),
+    attempts: z.number().int().nonnegative(),
+    output: z.string().optional(),
+    error: z.string().optional(),
+});
+export const taskSchema = z.object({
+    id: z.string().min(1),
+    title: z.string().min(1),
+    sessionId: z.string().min(1).optional(),
+    status: taskStatusSchema,
+    steps: z.array(taskStepSchema),
+    currentStepIndex: z.number().int().nonnegative(),
+    approval: z
+        .object({
+        runId: z.string().min(1),
+        toolName: z.string().min(1),
+        reason: z.string(),
+    })
+        .optional(),
+    createdAt: z.string(),
+    updatedAt: z.string(),
+    error: z.string().optional(),
+});
+const agentTurnSubmit = {
+    type: "agent.turn.submit",
+    payload: z.object({
+        sessionId: z.string().min(1).optional(),
+        message: z.string().min(1),
+        attachments: z.array(attachmentSchema).optional(),
+    }),
+    response: z.object({
+        turnId: z.string().min(1),
+        status: turnStatusSchema,
+    }),
+};
+const agentTurnCancel = {
+    type: "agent.turn.cancel",
+    payload: z.object({ turnId: z.string().min(1) }),
+    response: z.object({
+        turnId: z.string().min(1),
+        status: turnStatusSchema,
+    }),
+};
+/**
+ * `turn.approve` — answers a `turn.approval_required` event (HITL).
+ *
+ * The client sends `approved` plus optionally `editedArgs` (rewritten tool
+ * arguments the gateway must use instead of the proposed ones). The gateway
+ * answers `resumed: true` when the turn continues after the decision, or
+ * `resumed: false` when the runId is no longer pending (timed out or already
+ * handled).
+ */
+const turnApprove = {
+    type: "turn.approve",
+    payload: z.object({
+        /** The runId from the matching `turn.approval_required` event. */
+        runId: z.string().min(1),
+        approved: z.boolean(),
+        editedArgs: z.record(z.string(), z.unknown()).optional(),
+    }),
+    response: z.object({
+        runId: z.string(),
+        approved: z.boolean(),
+        resumed: z.boolean(),
+    }),
+};
+const sessionList = {
+    type: "session.list",
+    payload: z.object({}),
+    response: z.object({ sessions: z.array(sessionSchema) }),
+};
+const sessionGet = {
+    type: "session.get",
+    payload: z.object({ sessionId: z.string().min(1) }),
+    response: z.object({ session: sessionSchema, messages: z.array(messageSchema) }),
+};
+const sessionCreate = {
+    type: "session.create",
+    payload: z.object({ title: z.string().min(1).optional() }),
+    response: z.object({ session: sessionSchema }),
+};
+const sessionDelete = {
+    type: "session.delete",
+    payload: z.object({ sessionId: z.string().min(1) }),
+    response: okSchema,
+};
+const sessionRename = {
+    type: "session.rename",
+    payload: z.object({ sessionId: z.string().min(1), title: z.string().min(1).max(200) }),
+    response: z.object({ session: sessionSchema }),
+};
+const sessionUndo = {
+    type: "session.undo",
+    payload: z.object({ sessionId: z.string().min(1) }),
+    response: z.object({ removedCount: z.number().int().nonnegative() }),
+};
+const sessionBranch = {
+    type: "session.branch",
+    payload: z.object({
+        sessionId: z.string().min(1),
+        title: z.string().min(1).max(200).optional(),
+    }),
+    response: z.object({ session: sessionSchema }),
+};
+const sessionCheckpoint = {
+    type: "session.checkpoint",
+    payload: z.object({
+        sessionId: z.string().min(1),
+        /** Omit to checkpoint the latest message. */
+        messageId: z.string().min(1).optional(),
+    }),
+    response: z.object({ message: messageSchema }),
+};
+const sessionVariantCreate = {
+    type: "session.variant.create",
+    payload: z.object({
+        sessionId: z.string().min(1),
+        messageId: z.string().min(1),
+        content: z.string(),
+    }),
+    response: z.object({ variant: variantSchema }),
+};
+const sessionVariantSelect = {
+    type: "session.variant.select",
+    payload: z.object({
+        sessionId: z.string().min(1),
+        messageId: z.string().min(1),
+        /** 0 re-selects the base row. */
+        variantIndex: z.number().int().nonnegative(),
+    }),
+    response: z.object({ message: messageSchema }),
+};
+const sessionVariantList = {
+    type: "session.variant.list",
+    payload: z.object({
+        sessionId: z.string().min(1),
+        messageId: z.string().min(1),
+    }),
+    response: z.object({ variants: z.array(variantSchema) }),
+};
+const providerList = {
+    type: "provider.list",
+    payload: z.object({}),
+    response: z.object({ providers: z.array(providerSchema) }),
+};
+const providerSave = {
+    type: "provider.save",
+    payload: z.object({ provider: providerInputSchema }),
+    response: z.object({ provider: providerSchema }),
+};
+const providerTest = {
+    type: "provider.test",
+    payload: z.object({ id: z.string().min(1) }),
+    response: z.object({
+        ok: z.boolean(),
+        latencyMs: z.number().int().nonnegative().optional(),
+        detail: z.string().optional(),
+    }),
+};
+const providerActivate = {
+    type: "provider.activate",
+    payload: z.object({ id: z.string().min(1) }),
+    response: z.object({ provider: providerSchema }),
+};
+const providerDelete = {
+    type: "provider.delete",
+    payload: z.object({ id: z.string().min(1) }),
+    response: okSchema,
+};
+const scheduleList = {
+    type: "schedule.list",
+    payload: z.object({}),
+    response: z.object({ schedules: z.array(scheduleSchema) }),
+};
+const scheduleCreate = {
+    type: "schedule.create",
+    payload: z.object({
+        name: z.string().min(1),
+        cron: z.string().min(1),
+        prompt: z.string().min(1),
+        enabled: z.boolean().optional(),
+    }),
+    response: z.object({ schedule: scheduleSchema }),
+};
+const scheduleUpdate = {
+    type: "schedule.update",
+    payload: z.object({
+        id: z.string().min(1),
+        name: z.string().min(1).optional(),
+        cron: z.string().min(1).optional(),
+        prompt: z.string().min(1).optional(),
+        enabled: z.boolean().optional(),
+    }),
+    response: z.object({ schedule: scheduleSchema }),
+};
+const scheduleDelete = {
+    type: "schedule.delete",
+    payload: z.object({ id: z.string().min(1) }),
+    response: okSchema,
+};
+const scheduleToggle = {
+    type: "schedule.toggle",
+    payload: z.object({
+        id: z.string().min(1),
+        enabled: z.boolean(),
+    }),
+    response: z.object({ schedule: scheduleSchema }),
+};
+const memorySearch = {
+    type: "memory.search",
+    payload: z.object({
+        query: z.string().min(1),
+        limit: z.number().int().positive().max(100).optional(),
+    }),
+    response: z.object({ results: z.array(memoryHitSchema) }),
+};
+const memoryNote = {
+    type: "memory.note",
+    payload: z.object({
+        text: z.string().min(1).max(65_536).refine((text) => new TextEncoder().encode(text).byteLength <= 65_536, "text must not exceed 64 KiB"),
+        meta: z.record(z.string(), z.string()).refine((meta) => Object.keys(meta).length <= 32, "meta must not exceed 32 entries").optional(),
+    }),
+    response: z.object({ ok: z.literal(true), id: z.string().min(1) }),
+};
+const channelList = {
+    type: "channel.list",
+    payload: z.object({}),
+    response: z.object({ channels: z.array(channelSchema) }),
+};
+const gatewayHealth = {
+    type: "gateway.health",
+    payload: z.object({}),
+    response: z.object({
+        ok: z.boolean(),
+        version: z.string(),
+        wireVersion: z.number().int(),
+    }),
+};
+// ---------------------------------------------------------------------------
+// Background task runner commands (wire v1 additive).
+// ---------------------------------------------------------------------------
+/**
+ * `task.create` — enqueue a new background task: an ordered list of agent
+ * turns (steps) the gateway runs one after another, emitting `task.*` events.
+ * The response carries the full task record, with server-generated step ids.
+ */
+const taskCreate = {
+    type: "task.create",
+    payload: z.object({
+        title: z.string().min(1),
+        steps: z.array(z.object({ prompt: z.string().min(1) })).min(1),
+    }),
+    response: z.object({ task: taskSchema }),
+};
+const taskList = {
+    type: "task.list",
+    payload: z.object({}),
+    response: z.object({ tasks: z.array(taskSchema) }),
+};
+const taskGet = {
+    type: "task.get",
+    payload: z.object({ id: z.string().min(1) }),
+    response: z.object({ task: taskSchema }),
+};
+/**
+ * `task.pause` — pause a queued/running task between steps. A paused task
+ * emits no further turn activity until `task.resume`.
+ */
+const taskPause = {
+    type: "task.pause",
+    payload: z.object({ id: z.string().min(1) }),
+    response: z.object({ task: taskSchema }),
+};
+/**
+ * `task.resume` — resume a paused task, or answer a task's
+ * `task.awaiting_approval` checkpoint (HITL): `approved` plus optional
+ * `editedArgs` mirror `turn.approve`. Both fields are optional so a plain
+ * resume needs only the task id.
+ */
+const taskResume = {
+    type: "task.resume",
+    payload: z.object({
+        id: z.string().min(1),
+        approved: z.boolean().optional(),
+        editedArgs: z.record(z.string(), z.unknown()).optional(),
+    }),
+    response: z.object({ task: taskSchema }),
+};
+const taskCancel = {
+    type: "task.cancel",
+    payload: z.object({ id: z.string().min(1) }),
+    response: okSchema,
+};
+/**
+ * `task.redirect` — steer a running task: the gateway injects `message` as
+ * additional context before the next step starts.
+ */
+const taskRedirect = {
+    type: "task.redirect",
+    payload: z.object({
+        id: z.string().min(1),
+        message: z.string().min(1),
+    }),
+    response: z.object({ task: taskSchema }),
+};
+/**
+ * `task.retry` — re-run a failed (or interrupted) task starting at `fromStep`
+ * (default: the failed step). Steps already done are not re-run.
+ */
+const taskRetry = {
+    type: "task.retry",
+    payload: z.object({
+        id: z.string().min(1),
+        fromStep: z.number().int().nonnegative().optional(),
+    }),
+    response: z.object({ task: taskSchema }),
+};
+/** Every known command type, mapped to its payload/response schemas. */
+export const COMMAND_SCHEMAS = {
+    "agent.turn.submit": agentTurnSubmit,
+    "agent.turn.cancel": agentTurnCancel,
+    "turn.approve": turnApprove,
+    "session.list": sessionList,
+    "session.get": sessionGet,
+    "session.create": sessionCreate,
+    "session.delete": sessionDelete,
+    "session.rename": sessionRename,
+    "session.undo": sessionUndo,
+    "session.branch": sessionBranch,
+    "session.checkpoint": sessionCheckpoint,
+    "session.variant.create": sessionVariantCreate,
+    "session.variant.select": sessionVariantSelect,
+    "session.variant.list": sessionVariantList,
+    "provider.list": providerList,
+    "provider.save": providerSave,
+    "provider.test": providerTest,
+    "provider.activate": providerActivate,
+    "provider.delete": providerDelete,
+    "schedule.list": scheduleList,
+    "schedule.create": scheduleCreate,
+    "schedule.update": scheduleUpdate,
+    "schedule.delete": scheduleDelete,
+    "schedule.toggle": scheduleToggle,
+    "memory.search": memorySearch,
+    "memory.note": memoryNote,
+    "channel.list": channelList,
+    "gateway.health": gatewayHealth,
+    "task.create": taskCreate,
+    "task.list": taskList,
+    "task.get": taskGet,
+    "task.pause": taskPause,
+    "task.resume": taskResume,
+    "task.cancel": taskCancel,
+    "task.redirect": taskRedirect,
+    "task.retry": taskRetry,
+    // Additive extra commands (each module documents its own defs).
+    ...SCHEDULER_EXTRA_COMMAND_DEFS,
+    ...CHANNEL_EXTRA_COMMAND_DEFS,
+};
+/**
+ * Validate an envelope's payload against the schema registered for its `type`.
+ * Throws {@link ProtocolError}:
+ * - UNKNOWN_COMMAND when `type` is not registered,
+ * - INVALID_PAYLOAD when the payload fails its schema (zod issues in `details`).
+ */
+export function parseCommand(envelope) {
+    const def = COMMAND_SCHEMAS[envelope.type];
+    if (!def) {
+        throw new ProtocolError("UNKNOWN_COMMAND", `Unknown command type: ${envelope.type}`, { type: envelope.type });
+    }
+    const result = def.payload.safeParse(envelope.payload);
+    if (!result.success) {
+        throw new ProtocolError("INVALID_PAYLOAD", `Invalid payload for command ${def.type}: ${result.error.message}`, { type: def.type, issues: result.error.issues });
+    }
+    return { type: def.type, payload: result.data };
+}
+/**
+ * Validate a raw response body for a given command type.
+ * Throws {@link ProtocolError} with code INVALID_PAYLOAD on schema mismatch.
+ */
+export function parseCommandResponse(type, raw) {
+    const def = COMMAND_SCHEMAS[type];
+    const result = def.response.safeParse(raw);
+    if (!result.success) {
+        throw new ProtocolError("INVALID_PAYLOAD", `Invalid response for command ${type}: ${result.error.message}`, { type, issues: result.error.issues });
+    }
+    return result.data;
+}

package/dist/node_modules/@boombot/protocol/gateway-protocol/envelope.d.ts

@@ -0,0 +1,32 @@
+/**
+ * The wire envelope. Every command sent to `POST /v1/commands` is wrapped in
+ * this envelope; the gateway replies with the same envelope shape, where
+ * `type` is the response's command type and `payload` the response body.
+ *
+ * `protocolVersion` is a literal: any value other than {@link WIRE_VERSION}
+ * is rejected with a VERSION_MISMATCH error (see `parseEnvelope`).
+ */
+export interface Envelope<TType extends string, TPayload> {
+    protocolVersion: 1;
+    requestId: string;
+    type: TType;
+    payload: TPayload;
+}
+/**
+ * Current wire version. Independent from the product version: bumping the
+ * product does NOT change this value; only a breaking protocol change does.
+ */
+export declare const WIRE_VERSION: 1;
+/**
+ * Build a request envelope. A `requestId` is generated with
+ * `crypto.randomUUID()` when not supplied; clients should keep it stable
+ * across retries so the gateway can deduplicate.
+ */
+export declare function createEnvelope<TType extends string, TPayload>(type: TType, payload: TPayload, requestId?: string): Envelope<TType, TPayload>;
+/**
+ * Validate a raw value as an envelope. Accepts parsed JSON (objects) or a
+ * JSON string. Throws {@link ProtocolError} with code:
+ * - INVALID_ENVELOPE: not an object, or missing/invalid `requestId` / `type` / `payload`.
+ * - VERSION_MISMATCH: `protocolVersion` present but not equal to {@link WIRE_VERSION}.
+ */
+export declare function parseEnvelope(raw: unknown): Envelope<string, unknown>;

package/dist/node_modules/@boombot/protocol/gateway-protocol/envelope.js

@@ -0,0 +1,61 @@
+import { randomUUID } from "node:crypto";
+import { ProtocolError } from "./errors.js";
+/**
+ * Current wire version. Independent from the product version: bumping the
+ * product does NOT change this value; only a breaking protocol change does.
+ */
+export const WIRE_VERSION = 1;
+/**
+ * Build a request envelope. A `requestId` is generated with
+ * `crypto.randomUUID()` when not supplied; clients should keep it stable
+ * across retries so the gateway can deduplicate.
+ */
+export function createEnvelope(type, payload, requestId) {
+    return {
+        protocolVersion: WIRE_VERSION,
+        requestId: requestId ?? randomUUID(),
+        type,
+        payload,
+    };
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/**
+ * Validate a raw value as an envelope. Accepts parsed JSON (objects) or a
+ * JSON string. Throws {@link ProtocolError} with code:
+ * - INVALID_ENVELOPE: not an object, or missing/invalid `requestId` / `type` / `payload`.
+ * - VERSION_MISMATCH: `protocolVersion` present but not equal to {@link WIRE_VERSION}.
+ */
+export function parseEnvelope(raw) {
+    let value = raw;
+    if (typeof raw === "string") {
+        try {
+            value = JSON.parse(raw);
+        }
+        catch {
+            throw new ProtocolError("INVALID_ENVELOPE", "Envelope is not valid JSON");
+        }
+    }
+    if (!isRecord(value)) {
+        throw new ProtocolError("INVALID_ENVELOPE", "Envelope must be an object");
+    }
+    if (value.protocolVersion !== WIRE_VERSION) {
+        throw new ProtocolError("VERSION_MISMATCH", `Unsupported protocol version: expected ${WIRE_VERSION}, got ${String(value.protocolVersion)}`, { expected: WIRE_VERSION, received: value.protocolVersion });
+    }
+    if (typeof value.requestId !== "string" || value.requestId.length === 0) {
+        throw new ProtocolError("INVALID_ENVELOPE", "Envelope must have a non-empty string requestId");
+    }
+    if (typeof value.type !== "string" || value.type.length === 0) {
+        throw new ProtocolError("INVALID_ENVELOPE", "Envelope must have a non-empty string type");
+    }
+    if (!("payload" in value)) {
+        throw new ProtocolError("INVALID_ENVELOPE", "Envelope must have a payload");
+    }
+    return {
+        protocolVersion: WIRE_VERSION,
+        requestId: value.requestId,
+        type: value.type,
+        payload: value.payload,
+    };
+}

package/dist/node_modules/@boombot/protocol/gateway-protocol/errors.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Protocol-level errors shared by every command/event parser in this package.
+ *
+ * Every parse helper throws {@link ProtocolError} on invalid input so that
+ * callers (gateway server, web client) only have to handle one error type.
+ */
+/** Machine-readable protocol error codes. Additive-first: new codes are added, never renamed. */
+export type ProtocolErrorCode = "INVALID_ENVELOPE" | "UNKNOWN_COMMAND" | "INVALID_PAYLOAD" | "INVALID_EVENT" | "VERSION_MISMATCH" | "NOT_CONFIGURED" | "SESSION_NOT_FOUND";
+export declare class ProtocolError extends Error {
+    readonly code: ProtocolErrorCode;
+    readonly details?: unknown;
+    constructor(code: ProtocolErrorCode, message: string, details?: unknown);
+}

package/dist/node_modules/@boombot/protocol/gateway-protocol/errors.js

@@ -0,0 +1,16 @@
+/**
+ * Protocol-level errors shared by every command/event parser in this package.
+ *
+ * Every parse helper throws {@link ProtocolError} on invalid input so that
+ * callers (gateway server, web client) only have to handle one error type.
+ */
+export class ProtocolError extends Error {
+    code;
+    details;
+    constructor(code, message, details) {
+        super(message);
+        this.name = "ProtocolError";
+        this.code = code;
+        this.details = details;
+    }
+}