@theowlops/boombot 0.0.0-stage → 1.1.1

package/dist/gateway/handlers/index.js

@@ -0,0 +1,66 @@
+/**
+ * Register every command handler on the gateway registry.
+ *
+ * Each domain executor owns its `register*Handlers` function; this module is
+ * the coordinator-owned assembly point. Handler modules were built against
+ * minimal structural registry interfaces, so small adapters live here:
+ *
+ * - providers: `registerProviderHandlers` needs `{ register, providerService }`
+ *   (F's interface carries the service on the registry object).
+ */
+import { registerChannelHandlers } from '@boombot/channels';
+import { registerScheduleHandlers } from '@boombot/cronjobs';
+import { registerMemoryHandlers } from './memory.js';
+import { registerProviderHandlers } from './providers.js';
+import { registerSessionHandlers } from './sessions.js';
+import { registerSystemHandlers } from './system.js';
+import { registerTaskHandlers } from './tasks.js';
+import { registerTurnHandlers } from './turn.js';
+/**
+ * Register all command handlers. Services must already be started
+ * (see `services.ts`): handlers read them from `ctx` (or module singletons
+ * for providers/channels, as those executors designed).
+ */
+export function registerAllHandlers(ctx, registry) {
+    registerTurnHandlers(registry);
+    registerSessionHandlers(registry);
+    registerSystemHandlers(registry);
+    registerScheduleHandlers(registry);
+    registerMemoryHandlers(registry);
+    // E's channel handlers take `(payload)`; A's dispatch calls
+    // `(ctx, payload, meta)`. Wrap instead of casting so `channel.pair`
+    // / `channel.unpair` receive the real payload (dispatch already
+    // validated it against COMMAND_SCHEMAS).
+    registerChannelHandlers({
+        register(type, handler) {
+            const wrapped = (_ctx, payload) => handler(payload);
+            registry.register(type, wrapped);
+        },
+    });
+    const providerService = ctx.providerService;
+    if (providerService === undefined) {
+        ctx.log('warn', 'provider service not started: provider.* commands unavailable');
+        return;
+    }
+    // F's registry interface is generic over command types and its handlers
+    // take `(payload)`. The adapter below forwards to A's concrete registry;
+    // dispatch validates payloads/responses against the protocol schemas at
+    // runtime, so the shapes always line up.
+    registerProviderHandlers({
+        providerService,
+        register(type, handler) {
+            const wrapped = (_ctx, payload) => handler(payload);
+            registry.register(type, wrapped);
+        },
+    });
+    // Background task runner handlers (additive). The task handlers read
+    // `ctx.taskService` at dispatch time and throw a clear error when it is
+    // missing; the check below only skips registration for boot-time clarity
+    // and never affects the providers registered above.
+    if (ctx.taskService === undefined) {
+        ctx.log('warn', 'task service not started: task.* commands unavailable');
+    }
+    else {
+        registerTaskHandlers(registry);
+    }
+}

package/dist/gateway/handlers/memory.js

@@ -0,0 +1,54 @@
+/**
+ * Command handlers for the memory surface: `memory.search` and the additive
+ * `memory.note` command from `@boombot/protocol`.
+ *
+ * `registerMemoryHandlers(registry)` wires both handlers. The registry is
+ * kept structural and minimal on purpose — the real dispatch registry
+ * (executor A) only needs to satisfy:
+ *
+ * ```ts
+ * interface CommandHandlerRegistry {
+ *   handle(
+ *     type: string,
+ *     handler: (payload: unknown, ctx: MemoryHandlerContext) => Promise<unknown>,
+ *   ): void;
+ * }
+ * ```
+ *
+ * Handlers validate payloads against the protocol zod schemas and validate
+ * their responses the same way before returning, so a schema drift fails
+ * loudly here instead of on the client.
+ *
+ * When `ctx.memoryService` is absent (service failed to start), handlers
+ * throw a clear error — the dispatch layer maps it to an error response and
+ * the turn loop degrades (executor B treats a missing/failed recall as
+ * "no memories", never as a turn failure).
+ */
+import { COMMAND_SCHEMAS } from "@boombot/protocol";
+const searchPayload = COMMAND_SCHEMAS["memory.search"].payload;
+const searchResponse = COMMAND_SCHEMAS["memory.search"].response;
+const notePayload = COMMAND_SCHEMAS["memory.note"].payload;
+const noteResponse = COMMAND_SCHEMAS["memory.note"].response;
+function requireService(ctx) {
+    const service = ctx.memoryService;
+    if (service === undefined) {
+        throw new Error("memory service is not started");
+    }
+    return service;
+}
+async function handleMemorySearch(ctx, payload) {
+    const { query, limit } = searchPayload.parse(payload);
+    const service = requireService(ctx);
+    const results = await service.search(query, { limit });
+    return searchResponse.parse({ results });
+}
+async function handleMemoryNote(ctx, payload) {
+    const { text, meta } = notePayload.parse(payload);
+    const { id } = await requireService(ctx).note(text, meta);
+    return noteResponse.parse({ ok: true, id });
+}
+/** Register the memory command handlers on the gateway registry. */
+export function registerMemoryHandlers(registry) {
+    registry.register("memory.search", handleMemorySearch);
+    registry.register("memory.note", handleMemoryNote);
+}

package/dist/gateway/handlers/providers.js

@@ -0,0 +1,73 @@
+/**
+ * `provider.*` command handlers for the gateway.
+ *
+ * Each handler validates against the wire schemas in
+ * `@boombot/protocol` and delegates to the `ProviderService` booted
+ * by `services/providers.ts`. Responses follow the protocol exactly:
+ *
+ * - `provider.list` → `{ providers }` (wire `providerSchema`; keys never echoed)
+ * - `provider.save` → `{ provider }` (`apiKey` in the payload is write-only)
+ * - `provider.test` → `{ ok, latencyMs, detail? }`; runs a REAL probe and, on
+ *   success, stores the discovered model list on the provider record.
+ * - `provider.activate` → `{ provider }` (exactly one active provider)
+ * - `provider.delete` → `{ ok: true }`
+ *
+ * The web client (`apps/web/src/gateway/client.ts`) maps `provider.test`'s
+ * `detail` to its `error` field — this file keeps that contract.
+ */
+import { providerInputSchema, ProtocolError, probeProvider, } from "@boombot/protocol";
+export function registerProviderHandlers(registry) {
+    const service = registry.providerService;
+    registry.register("provider.list", async () => ({
+        providers: await service.list(),
+    }));
+    registry.register("provider.save", async (payload) => {
+        const parsed = providerInputSchema.safeParse(payload.provider);
+        if (!parsed.success) {
+            throw new ProtocolError("INVALID_PAYLOAD", `Invalid provider.save payload: ${parsed.error.message}`, { type: "provider.save", issues: parsed.error.issues });
+        }
+        return { provider: await service.save(parsed.data) };
+    });
+    registry.register("provider.test", async (payload) => {
+        const provider = (await service.list()).find((p) => p.id === payload.id);
+        if (!provider) {
+            return {
+                ok: false,
+                latencyMs: 0,
+                detail: `Provider '${payload.id}' not found.`,
+            };
+        }
+        const apiKey = await service.getApiKey(payload.id);
+        const startedAt = Date.now();
+        const probe = await probeProvider({ kind: provider.kind, baseUrl: provider.baseUrl }, apiKey ?? undefined);
+        const latencyMs = Date.now() - startedAt;
+        if (probe.ok) {
+            // Persist discovered models so resolveLlm() has a default model.
+            if (probe.models && probe.models.length > 0) {
+                await service.save({
+                    id: provider.id,
+                    name: provider.name,
+                    kind: provider.kind,
+                    ...(provider.baseUrl ? { baseUrl: provider.baseUrl } : {}),
+                    models: probe.models,
+                });
+            }
+            const count = probe.models?.length ?? 0;
+            return {
+                ok: true,
+                latencyMs,
+                detail: count > 0
+                    ? `${count} model${count === 1 ? "" : "s"} available: ${probe.models?.slice(0, 5).join(", ")}${count > 5 ? ", …" : ""}`
+                    : "Probe succeeded.",
+            };
+        }
+        return { ok: false, latencyMs, detail: probe.error ?? "Probe failed." };
+    });
+    registry.register("provider.activate", async (payload) => ({
+        provider: await service.activate(payload.id),
+    }));
+    registry.register("provider.delete", async (payload) => {
+        await service.delete(payload.id);
+        return { ok: true };
+    });
+}

package/dist/gateway/handlers/registry.js

@@ -0,0 +1,39 @@
+import { parseCommand, parseCommandResponse, ProtocolError } from '@boombot/protocol';
+/**
+ * Command handler registry for `POST /v1/commands`.
+ *
+ * `dispatch` runs three steps, all driven by the protocol package
+ * (`@boombot/protocol`):
+ *  1. Validate the envelope payload against `COMMAND_SCHEMAS` (`parseCommand`).
+ *     Unknown command types and schema violations throw `ProtocolError`.
+ *  2. Call the registered handler for the command type. A known command with
+ *     no handler is also an `UNKNOWN_COMMAND` error (fail closed).
+ *  3. Validate the handler's response with `parseCommandResponse` so a buggy
+ *     handler can never put an off-contract body on the wire.
+ *
+ * The server maps `ProtocolError` to a 400 error envelope; unexpected handler
+ * failures become 500.
+ */
+export class HandlerRegistry {
+    handlers = new Map();
+    register(type, handler) {
+        if (this.handlers.has(type)) {
+            throw new Error(`Handler already registered for command type "${type}"`);
+        }
+        this.handlers.set(type, handler);
+    }
+    async dispatch(type, ctx, payload, meta) {
+        const parsed = parseCommand({
+            protocolVersion: 1,
+            requestId: meta.requestId,
+            type,
+            payload,
+        });
+        const handler = this.handlers.get(parsed.type);
+        if (!handler) {
+            throw new ProtocolError('UNKNOWN_COMMAND', `No handler registered for command "${parsed.type}"`, { type: parsed.type });
+        }
+        const result = await handler(ctx, parsed.payload, meta);
+        return parseCommandResponse(parsed.type, result);
+    }
+}

package/dist/gateway/handlers/sessions.js

@@ -0,0 +1,188 @@
+/**
+ * `session.*` command handlers — backed by the durable `SessionStore`.
+ *
+ * Shapes follow `packages/gateway-protocol` v1 exactly:
+ * - `session.list` → `{ sessions }`
+ * - `session.create` → `{ session }`
+ * - `session.rename` → `{ session }`
+ * - `session.delete` → `{ ok }`
+ * - `session.checkpoint` → `{ message }` (P1-6: mark a context checkpoint;
+ *   prompt projection drops everything before the newest checkpoint)
+ * - `session.variant.create` → `{ variant }` (P2-3: store an alternate
+ *   content at a message position)
+ * - `session.variant.select` → `{ message }` (P2-3: choose the active
+ *   variant; history reads and the prompt use it)
+ * - `session.variant.list` → `{ variants }` (P2-3: every variant at a position)
+ */
+import { ProtocolError } from '@boombot/protocol';
+import { SessionNotFoundError, VariantNotFoundError } from '../sessions.js';
+export function registerSessionHandlers(registry) {
+    registry.register('session.list', async (ctx) => {
+        const list = ctx.sessions.list();
+        return { sessions: list.filter((s) => !s.id.startsWith('sch_sess_')) };
+    });
+    registry.register('session.get', async (ctx, payload) => {
+        const sessionId = payload.sessionId;
+        const session = ctx.sessions.get(sessionId);
+        if (!session) {
+            throw new ProtocolError('SESSION_NOT_FOUND', `Session not found: ${sessionId}`, { sessionId });
+        }
+        return { session, messages: ctx.sessions.getMessages(sessionId) };
+    });
+    registry.register('session.create', async (ctx, payload) => {
+        const title = typeof payload === 'object' && payload !== null
+            ? payload['title']
+            : undefined;
+        const session = ctx.sessions.create(typeof title === 'string' && title.length > 0 ? title : undefined);
+        return { session };
+    });
+    registry.register('session.rename', async (ctx, payload) => {
+        const record = typeof payload === 'object' && payload !== null
+            ? payload
+            : undefined;
+        const sessionId = record?.['sessionId'];
+        const title = record?.['title'];
+        if (typeof sessionId !== 'string' || sessionId.length === 0) {
+            throw new ProtocolError('INVALID_PAYLOAD', 'session.rename requires payload { sessionId, title }.');
+        }
+        if (typeof title !== 'string' || title.trim().length === 0) {
+            throw new ProtocolError('INVALID_PAYLOAD', 'session.rename requires payload { sessionId, title }.');
+        }
+        try {
+            return { session: ctx.sessions.rename(sessionId, title.trim()) };
+        }
+        catch (error) {
+            if (error instanceof SessionNotFoundError) {
+                throw new ProtocolError('SESSION_NOT_FOUND', error.message, { sessionId });
+            }
+            throw error;
+        }
+    });
+    registry.register('session.undo', async (ctx, payload) => {
+        const sessionId = readSessionId('session.undo', payload);
+        try {
+            return { removedCount: ctx.sessions.undoLastExchange(sessionId) };
+        }
+        catch (error) {
+            if (error instanceof SessionNotFoundError) {
+                throw new ProtocolError('SESSION_NOT_FOUND', error.message, { sessionId });
+            }
+            throw error;
+        }
+    });
+    registry.register('session.branch', async (ctx, payload) => {
+        const sessionId = readSessionId('session.branch', payload);
+        const title = payload['title'];
+        if (title !== undefined && (typeof title !== 'string' || title.trim() === '')) {
+            throw new ProtocolError('INVALID_PAYLOAD', 'session.branch title must be non-empty when provided');
+        }
+        try {
+            return { session: ctx.sessions.branch(sessionId, typeof title === 'string' ? title : undefined) };
+        }
+        catch (error) {
+            if (error instanceof SessionNotFoundError) {
+                throw new ProtocolError('SESSION_NOT_FOUND', error.message, { sessionId });
+            }
+            throw error;
+        }
+    });
+    registry.register('session.delete', async (ctx, payload) => {
+        const sessionId = readSessionId('session.delete', payload);
+        ctx.sessions.delete(sessionId);
+        return { ok: true };
+    });
+    registry.register('session.checkpoint', async (ctx, payload) => {
+        const record = typeof payload === 'object' && payload !== null
+            ? payload
+            : undefined;
+        const sessionId = readSessionId('session.checkpoint', payload);
+        const messageId = record?.['messageId'];
+        if (messageId !== undefined && (typeof messageId !== 'string' || messageId.length === 0)) {
+            throw new ProtocolError('INVALID_PAYLOAD', 'session.checkpoint: messageId must be a non-empty string when provided.');
+        }
+        try {
+            return {
+                message: ctx.sessions.markCheckpoint(sessionId, typeof messageId === 'string' ? messageId : undefined),
+            };
+        }
+        catch (error) {
+            if (error instanceof SessionNotFoundError) {
+                throw new ProtocolError('SESSION_NOT_FOUND', error.message, { sessionId });
+            }
+            throw error;
+        }
+    });
+    registry.register('session.variant.create', async (ctx, payload) => {
+        const record = typeof payload === 'object' && payload !== null
+            ? payload
+            : undefined;
+        const sessionId = readSessionId('session.variant.create', payload);
+        const messageId = readMessageId('session.variant.create', record);
+        const content = record?.['content'];
+        if (typeof content !== 'string') {
+            throw new ProtocolError('INVALID_PAYLOAD', 'session.variant.create: content must be a string.');
+        }
+        try {
+            return { variant: ctx.sessions.createVariant(sessionId, messageId, content) };
+        }
+        catch (error) {
+            throw mapVariantError('session.variant.create', sessionId, error);
+        }
+    });
+    registry.register('session.variant.select', async (ctx, payload) => {
+        const record = typeof payload === 'object' && payload !== null
+            ? payload
+            : undefined;
+        const sessionId = readSessionId('session.variant.select', payload);
+        const messageId = readMessageId('session.variant.select', record);
+        const variantIndex = record?.['variantIndex'];
+        if (typeof variantIndex !== 'number' || !Number.isInteger(variantIndex) || variantIndex < 0) {
+            throw new ProtocolError('INVALID_PAYLOAD', 'session.variant.select: variantIndex must be a non-negative integer (0 = base row).');
+        }
+        try {
+            return { message: ctx.sessions.selectVariant(sessionId, messageId, variantIndex) };
+        }
+        catch (error) {
+            throw mapVariantError('session.variant.select', sessionId, error);
+        }
+    });
+    registry.register('session.variant.list', async (ctx, payload) => {
+        const record = typeof payload === 'object' && payload !== null
+            ? payload
+            : undefined;
+        const sessionId = readSessionId('session.variant.list', payload);
+        const messageId = readMessageId('session.variant.list', record);
+        try {
+            return { variants: ctx.sessions.listVariants(sessionId, messageId) };
+        }
+        catch (error) {
+            throw mapVariantError('session.variant.list', sessionId, error);
+        }
+    });
+}
+function readSessionId(command, payload) {
+    const sessionId = typeof payload === 'object' && payload !== null
+        ? payload['sessionId']
+        : undefined;
+    if (typeof sessionId !== 'string' || sessionId.length === 0) {
+        throw new ProtocolError('INVALID_PAYLOAD', `${command}: sessionId must be a non-empty string`);
+    }
+    return sessionId;
+}
+function readMessageId(command, record) {
+    const messageId = record?.['messageId'];
+    if (typeof messageId !== 'string' || messageId.length === 0) {
+        throw new ProtocolError('INVALID_PAYLOAD', `${command}: messageId must be a non-empty string`);
+    }
+    return messageId;
+}
+/** Map store-level variant errors to protocol errors. */
+function mapVariantError(command, sessionId, error) {
+    if (error instanceof SessionNotFoundError) {
+        return new ProtocolError('SESSION_NOT_FOUND', error.message, { sessionId });
+    }
+    if (error instanceof VariantNotFoundError) {
+        return new ProtocolError('INVALID_PAYLOAD', `${command}: ${error.message}`, { sessionId });
+    }
+    throw error;
+}

package/dist/gateway/handlers/system.js

@@ -0,0 +1,12 @@
+/**
+ * `gateway.health` command handler.
+ *
+ * Mirrors `GET /healthz` (which needs no auth): `{ ok, version, wireVersion }`.
+ */
+import { WIRE_VERSION } from '@boombot/protocol';
+import { GATEWAY_VERSION } from '../server.js';
+export function registerSystemHandlers(registry) {
+    registry.register('gateway.health', async () => {
+        return { ok: true, version: GATEWAY_VERSION, wireVersion: WIRE_VERSION };
+    });
+}

package/dist/gateway/handlers/tasks.js

@@ -0,0 +1,191 @@
+/**
+ * Command handlers for `task.*` (background task runner):
+ * `task.create` / `task.list` / `task.get` / `task.pause` / `task.resume` /
+ * `task.cancel` / `task.redirect` / `task.retry`.
+ *
+ * Registered on the coordinator-owned command registry; each handler
+ * receives the service context (which carries the started task service),
+ * the validated command payload, and the request meta.
+ *
+ * `TaskError` codes from the runner map onto protocol errors the way
+ * `turn.approve` maps a missing approval: `NOT_FOUND` / `INVALID_STATE`
+ * become `INVALID_PAYLOAD` (client error, 400 via the server's
+ * ProtocolError mapping); anything else (e.g. `STORAGE`) propagates.
+ * Malformed payloads are also `INVALID_PAYLOAD` (400), never a 500 —
+ * only a missing task service stays a plain `Error` (genuine 500).
+ */
+import { TaskError } from '@boombot/core';
+import { ProtocolError } from '@boombot/protocol';
+export function registerTaskHandlers(registry) {
+    registry.register('task.create', async (ctx, payload) => {
+        const service = requireTaskService('task.create', ctx);
+        const { title, steps } = readCreatePayload(payload);
+        const task = await withTaskErrorMapping('task.create', title, () => service.createAndStart({ title, steps }));
+        return { task };
+    });
+    registry.register('task.list', async (ctx) => {
+        const service = requireTaskService('task.list', ctx);
+        const tasks = await service.list();
+        return { tasks };
+    });
+    registry.register('task.get', async (ctx, payload) => {
+        const service = requireTaskService('task.get', ctx);
+        const { id } = readIdPayload('task.get', payload);
+        const task = await service.get(id);
+        if (task === null) {
+            // Client error (400 via the server's ProtocolError mapping), not a
+            // 500: the task id is well-formed, it just does not exist.
+            throw new ProtocolError('INVALID_PAYLOAD', `task not found: ${id}`, { id });
+        }
+        return { task };
+    });
+    registry.register('task.pause', async (ctx, payload) => {
+        const service = requireTaskService('task.pause', ctx);
+        const { id } = readIdPayload('task.pause', payload);
+        const task = await withTaskErrorMapping('task.pause', id, () => service.pause(id));
+        return { task };
+    });
+    registry.register('task.resume', async (ctx, payload) => {
+        const service = requireTaskService('task.resume', ctx);
+        const { id, decision } = readResumePayload(payload);
+        const task = await withTaskErrorMapping('task.resume', id, () => service.resume(id, decision));
+        return { task };
+    });
+    registry.register('task.cancel', async (ctx, payload) => {
+        const service = requireTaskService('task.cancel', ctx);
+        const { id } = readIdPayload('task.cancel', payload);
+        const task = await withTaskErrorMapping('task.cancel', id, () => service.cancel(id));
+        return { task };
+    });
+    registry.register('task.redirect', async (ctx, payload) => {
+        const service = requireTaskService('task.redirect', ctx);
+        const { id, message } = readRedirectPayload(payload);
+        const task = await withTaskErrorMapping('task.redirect', id, () => service.redirect(id, message));
+        return { task };
+    });
+    registry.register('task.retry', async (ctx, payload) => {
+        const service = requireTaskService('task.retry', ctx);
+        const { id, fromStep } = readRetryPayload(payload);
+        const task = await withTaskErrorMapping('task.retry', id, () => service.retry(id, fromStep));
+        return { task };
+    });
+}
+function requireTaskService(command, ctx) {
+    const service = ctx.taskService;
+    if (service === undefined) {
+        throw new Error(`task service is not running: ${command} is unavailable`);
+    }
+    return service;
+}
+/** Run a runner call, mapping `TaskError` codes onto protocol errors. */
+async function withTaskErrorMapping(command, taskRef, fn) {
+    try {
+        return await fn();
+    }
+    catch (error) {
+        throw mapTaskError(command, taskRef, error);
+    }
+}
+function mapTaskError(command, taskRef, error) {
+    if (error instanceof TaskError) {
+        if (error.code === 'NOT_FOUND') {
+            return new ProtocolError('INVALID_PAYLOAD', `task not found: ${taskRef}`, {
+                id: taskRef,
+            });
+        }
+        if (error.code === 'INVALID_STATE') {
+            return new ProtocolError('INVALID_PAYLOAD', `${command}: ${error.message}`, {
+                id: taskRef,
+            });
+        }
+    }
+    return error instanceof Error ? error : new Error(`${command} failed: ${String(error)}`);
+}
+/**
+ * Read the task id. The wire contract (`COMMAND_SCHEMAS`) names the field
+ * `id`; the handler used to read `taskId`, which rejected every
+ * contract-conformant request.
+ */
+function readIdPayload(command, payload) {
+    if (typeof payload !== 'object' || payload === null) {
+        throw new ProtocolError('INVALID_PAYLOAD', `${command}: payload must be an object`);
+    }
+    const { id } = payload;
+    if (typeof id !== 'string' || id === '') {
+        throw new ProtocolError('INVALID_PAYLOAD', `${command}: id must be a non-empty string`);
+    }
+    return { id };
+}
+function readCreatePayload(payload) {
+    if (typeof payload !== 'object' || payload === null) {
+        throw new ProtocolError('INVALID_PAYLOAD', 'task.create: payload must be an object');
+    }
+    const record = payload;
+    const { title, steps } = record;
+    if (typeof title !== 'string' || title.trim() === '') {
+        throw new ProtocolError('INVALID_PAYLOAD', 'task.create: title must be a non-empty string');
+    }
+    if (!Array.isArray(steps) || steps.length === 0) {
+        throw new ProtocolError('INVALID_PAYLOAD', 'task.create: steps must be a non-empty array');
+    }
+    const parsed = steps.map((step, index) => {
+        if (typeof step !== 'object' || step === null) {
+            throw new ProtocolError('INVALID_PAYLOAD', `task.create: steps[${index}] must be an object`);
+        }
+        const prompt = step['prompt'];
+        if (typeof prompt !== 'string' || prompt.trim() === '') {
+            throw new ProtocolError('INVALID_PAYLOAD', `task.create: steps[${index}].prompt must be a non-empty string`);
+        }
+        return { prompt };
+    });
+    return { title, steps: parsed };
+}
+/**
+ * The wire contract carries the approval fields flat (`approved`,
+ * `editedArgs` — mirroring `turn.approve`); the handler used to expect a
+ * nested `decision` object, which rejected every contract-conformant
+ * request.
+ */
+function readResumePayload(payload) {
+    const { id } = readIdPayload('task.resume', payload);
+    const record = payload;
+    const approved = record['approved'];
+    const editedArgs = record['editedArgs'];
+    if (approved === undefined && editedArgs === undefined) {
+        return { id };
+    }
+    if (typeof approved !== 'boolean') {
+        throw new ProtocolError('INVALID_PAYLOAD', 'task.resume: approved must be a boolean when provided');
+    }
+    if (editedArgs !== undefined && (typeof editedArgs !== 'object' || editedArgs === null)) {
+        throw new ProtocolError('INVALID_PAYLOAD', 'task.resume: editedArgs must be an object when provided');
+    }
+    return {
+        id,
+        decision: {
+            approved,
+            ...(editedArgs !== undefined ? { editedArgs: editedArgs } : {}),
+        },
+    };
+}
+function readRedirectPayload(payload) {
+    const { id } = readIdPayload('task.redirect', payload);
+    const record = payload;
+    const message = record['message'];
+    if (typeof message !== 'string' || message.trim() === '') {
+        throw new ProtocolError('INVALID_PAYLOAD', 'task.redirect: message must be a non-empty string');
+    }
+    return { id, message };
+}
+function readRetryPayload(payload) {
+    const { id } = readIdPayload('task.retry', payload);
+    const record = payload;
+    const fromStep = record['fromStep'];
+    if (fromStep === undefined) {
+        return { id };
+    }
+    if (typeof fromStep !== 'number' || !Number.isInteger(fromStep) || fromStep < 0) {
+        throw new ProtocolError('INVALID_PAYLOAD', 'task.retry: fromStep must be a non-negative integer when provided');
+    }
+    return { id, fromStep };
+}