pi-sessions 0.10.0 → 0.11.1

package/README.md

@@ -34,7 +34,7 @@
 
 ## Install
 
-Requires Pi `0.80.10` or newer and Node `>=24 <26`.
+Requires Pi `0.82.1` or newer and Node `>=24 <26`.
 
 **From npm** (recommended):
 
@@ -65,15 +65,15 @@ Open the frontend implementation task in a session to the right.
 
 ## Features
 
-| Extension          | Surface                                           | What it does                                            |
-| ------------------ | ------------------------------------------------- | ------------------------------------------------------- |
-| Session Search     | `session_search` pi tool                          | Search through old sessions                             |
-| Session Ask        | `session_ask` pi tool                             | Ask questions about old sessions                        |
-| Session Handoff    | `session_handoff` pi tool, `/handoff` board       | Start and manage focused child sessions                 |
-| Session Messaging  | `session_send_message`, `session_cancel` pi tools | Coordinate between live Pi sessions and own subagents   |
-| Session Picker     | `Alt+O`                                           | Reference old sessions in your prompt                   |
-| Session Index      | `/session-index` slash command                    | Shows index status and rebuilds the local session index |
-| Session Auto Title | in background, `/title` slash command             | Give sessions titles                                    |
+| Extension          | Surface                                                                | What it does                                            |
+| ------------------ | ---------------------------------------------------------------------- | ------------------------------------------------------- |
+| Session Search     | `session_search` pi tool                                               | Search through old sessions                             |
+| Session Ask        | `session_ask` pi tool                                                  | Ask questions about old sessions                        |
+| Session Handoff    | `session_handoff` pi tool, `/handoff` board                            | Start and manage focused child sessions                 |
+| Session Messaging  | `session_reachable`, `session_send_message`, `session_cancel` pi tools | Coordinate between live Pi sessions and own subagents   |
+| Session Picker     | `Alt+O`                                                                | Reference old sessions in your prompt                   |
+| Session Index      | `/session-index` slash command                                         | Shows index status and rebuilds the local session index |
+| Session Auto Title | in background, `/title` slash command                                  | Give sessions titles                                    |
 
 Every feature is on by default. Turn one off with `enable: false` under its own settings namespace, which unregisters its tools and hooks.
 
@@ -93,16 +93,16 @@ Every feature is on by default. Turn one off with `enable: false` under its own
 
 ## Session Search
 
-`session_search` searches the local session index by text, repo, cwd, time range, file evidence, and whether a session is currently running.
+`session_search` searches the local session index by text, repo, cwd, time range, and file evidence.
 
-Queries support regular text for normal usage, quoted phrases, `AND` / `OR` / `NOT`, parentheses, and `-term` negation when matching needs to be stricter. Unquoted terms use prefix matching, quoted terms are exact. A search with no query returns matching sessions chronologically, newest first. Use `live: true` to restrict results to currently running sessions.
+Queries support regular text for normal usage, quoted phrases, `AND` / `OR` / `NOT`, parentheses, and `-term` negation when matching needs to be stricter. Unquoted terms use prefix matching, quoted terms are exact. A search with no query returns matching sessions chronologically, newest first.
 
 File filters distinguish read-or-write evidence from write-only evidence:
 
 - `files.touched`: sessions that read or changed a path
 - `files.changed`: sessions that changed a path
 
-Use `kind: "user"` or `kind: "subagent"` to filter by session type across the whole index. Use `relationScope: "branch"` to search subagents launched from the current conversation branch, or `relationScope: "tree"` to include subagents launched from abandoned branches as well.
+Use `kind: "user"` or `kind: "subagent"` to filter by session type across the whole index. Searching for sessions that can be addressed right now is a different question, answered by `session_reachable`.
 
 ## Session Handoff
 
@@ -116,7 +116,7 @@ Run `/handoff` to open the **Handoffs** board. The Subagents and User sessions t
 
 Agents can coordinate with live Pi sessions and their own subagents:
 
-- `session_search` with `live: true` lists live sessions
+- `session_reachable` lists the sessions this session can send messages to
 - `session_send_message` sends a message to a live session or own subagent
 - `session_cancel` aborts another live session's current turn
 
@@ -214,9 +214,10 @@ Note that generating titles for all sessions can take some time, and will hit yo
 - if you manually rename a session with `/name`, automatic retitling pauses for that session
 - Regenerate the title for the current session to resume automatic retitling
 - if unconfigured, it will attempt to use these models in order, first one that is available:
-  - `google/gemini-flash-lite-latest`
+  - `openai-codex/gpt-5.6-luna`
+  - `openai/gpt-5.6-luna`
   - `anthropic/claude-haiku-4-5`
-  - `openai/gpt-5.4-mini`
+  - `google/gemini-flash-lite-latest`
   - your currently configured model
 
 To change auto-titling settings, edit `~/.pi/agent/settings.json`:
@@ -227,20 +228,24 @@ To change auto-titling settings, edit `~/.pi/agent/settings.json`:
     "autoTitle": {
       "refreshTurns": 4,
       "timeoutSecs": 15,
+      "tokenBudget": 64,
       "model": "anthropic/claude-haiku-4-5",
       "thinkingLevel": "off",
-      "prompt": "Custom prompt that overrides the default."
+      "prompt": "Custom prompt that overrides the default.",
+      "persistRuns": false
     }
   }
 }
 ```
 
+`persistRuns` records each title request as its own session file under `~/.pi/agent/pi-sessions/session-auto-title/`, holding the exact prompt and response. Open one with `pi --session <file>` to see what the titling model was sent.
+
 ## Development
 
 ```bash
-npm install
-npm run check
-npm test
+mise trust && mise bootstrap
+mise run check
+mise run test
 ```
 
 For an end-to-end manual flow, see [SMOKE.md](./SMOKE.md).

package/dist/session-messaging/broker/client-frame.js

@@ -0,0 +1,62 @@
+// The broker runs as a detached raw-Node process with nothing installed next to
+// it, so client frames are validated by hand rather than against the TypeBox
+// schemas in shared/session-broker/protocol.ts. The broker only routes
+// envelopes, so it validates the routing fields and treats `envelope` as an
+// opaque object; the receiving client validates the envelope body in full.
+const CONTEXT = "Invalid session messaging client frame";
+export function parseClientFrame(value) {
+    const frame = requireObject(value, "/");
+    switch (frame.type) {
+        case "register":
+            return { type: "register", sessionId: requireString(frame.sessionId, "/sessionId") };
+        case "unregister":
+            return { type: "unregister" };
+        case "list":
+            return { type: "list", requestId: requireString(frame.requestId, "/requestId") };
+        case "send":
+            return {
+                type: "send",
+                requestId: requireString(frame.requestId, "/requestId"),
+                target: requireString(frame.target, "/target"),
+                envelope: requireObject(frame.envelope, "/envelope"),
+            };
+        case "incoming_ack": {
+            const error = optionalString(frame.error, "/error");
+            return {
+                type: "incoming_ack",
+                requestId: requireString(frame.requestId, "/requestId"),
+                delivered: requireBoolean(frame.delivered, "/delivered"),
+                ...(error === undefined ? {} : { error }),
+            };
+        }
+        default:
+            throw invalid("/type", "expected a known client frame type");
+    }
+}
+function requireObject(value, path) {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        throw invalid(path, "expected an object");
+    }
+    return value;
+}
+function requireString(value, path) {
+    if (typeof value !== "string") {
+        throw invalid(path, "expected a string");
+    }
+    return value;
+}
+function requireBoolean(value, path) {
+    if (typeof value !== "boolean") {
+        throw invalid(path, "expected a boolean");
+    }
+    return value;
+}
+function optionalString(value, path) {
+    if (value === undefined) {
+        return undefined;
+    }
+    return requireString(value, path);
+}
+function invalid(path, message) {
+    return new Error(`${CONTEXT}: ${path} ${message}`);
+}

package/dist/session-messaging/broker/process.js

@@ -2,8 +2,8 @@ import { mkdirSync, unlinkSync, writeFileSync } from "node:fs";
 import { createServer } from "node:net";
 import { join } from "node:path";
 import { readFrames, writeFrame } from "../../shared/session-broker/framing.js";
-import { CLIENT_FRAME_SCHEMA, } from "../../shared/session-broker/protocol.js";
 import { getSessionMessagingDir, getSessionMessagingSocketPath, } from "../../shared/session-broker/socket-path.js";
+import { parseClientFrame, } from "./client-frame.js";
 const SEND_TIMEOUT_MS = 10_000;
 const EXIT_IDLE_MS = 5_000;
 const KEEPALIVE_DELAY_MS = 5_000;
@@ -190,7 +190,7 @@ function handleConnection(socket) {
 }
 async function readConnection(socket, getSessionId, setSessionId) {
     try {
-        for await (const frame of readFrames(socket, CLIENT_FRAME_SCHEMA, "Invalid session messaging client frame")) {
+        for await (const frame of readFrames(socket, parseClientFrame)) {
             handleFrame(socket, frame, getSessionId, setSessionId);
         }
     }

package/dist/shared/session-broker/framing.js

@@ -1,10 +1,11 @@
 import { createInterface } from "node:readline";
-import { parseTypeBoxValue } from "../typebox.js";
 const MAX_FRAME_BYTES = 256 * 1024;
 export function writeFrame(socket, frame) {
     socket.write(`${JSON.stringify(frame)}\n`);
 }
-export async function* readFrames(socket, schema, context) {
+// The parser is injected so the detached broker can run with no dependencies
+// installed alongside it, while Pi-side callers keep using TypeBox schemas.
+export async function* readFrames(socket, parseFrame) {
     const reader = createInterface({ input: socket, crlfDelay: Number.POSITIVE_INFINITY });
     const lines = [];
     const waiters = [];
@@ -49,7 +50,7 @@ export async function* readFrames(socket, schema, context) {
             catch (parseError) {
                 throw parseError instanceof Error ? parseError : new Error(String(parseError));
             }
-            yield parseTypeBoxValue(schema, parsed, context);
+            yield parseFrame(parsed);
         }
     }
     finally {

package/extensions/pi-sessions.ts

@@ -9,6 +9,7 @@ import { installHandoff } from "./session-handoff/install.ts";
 import { installHooks } from "./session-hooks/install.ts";
 import { installIndex } from "./session-index/install.ts";
 import { installMessaging } from "./session-messaging/install.ts";
+import { createSessionReachableTool } from "./session-messaging/pi/reachable-tool.ts";
 import {
   createSessionCancelTool,
   createSessionSendMessageTool,
@@ -67,6 +68,18 @@ export default function piSessions(pi: ExtensionAPI): void {
       }),
     );
     pi.registerTool(createSessionCancelTool(subagents ?? messaging));
+    pi.registerTool(
+      createSessionReachableTool({
+        indexPath: index.path,
+        listSessions: () => messaging.listSessions(),
+        getRelationTo: messaging.getCachedRelationTo,
+        ...(subagents
+          ? {
+              listSubagents: async (scope) => (await subagents.roster.resolve(scope)).entries,
+            }
+          : {}),
+      }),
+    );
   }
   if (settings.features.handoff) {
     const board = {
@@ -88,7 +101,7 @@ export default function piSessions(pi: ExtensionAPI): void {
     );
   }
   if (settings.features.search) {
-    installSearch(pi, { settings, index, messaging, roster: subagents?.roster });
+    installSearch(pi, { settings, index });
   }
   if (settings.features.ask) {
     installAsk(pi, { settings, index, getModelRuntime });

package/extensions/session-auto-title/generate.ts

@@ -1,13 +1,10 @@
-import { appendFileSync, mkdirSync } from "node:fs";
-import { homedir } from "node:os";
-import { join } from "node:path";
 import type { ThinkingLevel } from "@earendil-works/pi-agent-core";
 import type { Api, Model, TextContent, UserMessage } from "@earendil-works/pi-ai";
 import type { ModelRuntime } from "@earendil-works/pi-coding-agent";
 import type { AutoTitleContext } from "./context.ts";
+import { type AutoTitleRun, startAutoTitleRun } from "./runs.ts";
 import type { AutoTitleTrigger } from "./state.ts";
 
-const AUTO_TITLE_MAX_TOKENS = 64;
 const AUTO_TITLE_CHAR_MAX = 80;
 
 export interface AutoTitleFailure {
@@ -20,7 +17,9 @@ export interface AutoTitleFailure {
 export interface AutoTitleGeneration {
   systemPrompt: string;
   timeoutMs: number;
+  tokenBudget: number;
   thinkingLevel: ThinkingLevel | undefined;
+  persistRuns: boolean;
 }
 
 export type AutoTitleGenerationResult =
@@ -66,35 +65,47 @@ export async function generateAutoTitle(
   const abortController = new AbortController();
   const timeoutId = setTimeout(() => abortController.abort(), generation.timeoutMs);
   const thinkingLevel = generation.thinkingLevel;
+  const run = generation.persistRuns
+    ? startAutoTitleRun({
+        cwd: context.cwd ?? process.cwd(),
+        model,
+        trigger,
+        systemPrompt: resolvedSystemPrompt,
+        tokenBudget: generation.tokenBudget,
+        thinkingLevel,
+        message,
+      })
+    : undefined;
 
   try {
-    const requestContext = {
-      systemPrompt: resolvedSystemPrompt,
-      messages: [message],
-    };
-    writeAutoTitleDebugRequest(model, trigger, requestContext);
-    const response = await modelRuntime.completeSimple(model, requestContext, {
-      maxTokens: AUTO_TITLE_MAX_TOKENS,
-      ...(thinkingLevel && thinkingLevel !== "off" ? { reasoning: thinkingLevel } : {}),
-      signal: abortController.signal,
-    });
-    writeAutoTitleDebugResponse(model, trigger, response);
+    const response = await modelRuntime.completeSimple(
+      model,
+      {
+        systemPrompt: resolvedSystemPrompt,
+        messages: [message],
+      },
+      {
+        maxTokens: generation.tokenBudget,
+        ...(thinkingLevel && thinkingLevel !== "off" ? { reasoning: thinkingLevel } : {}),
+        signal: abortController.signal,
+      },
+    );
+    run?.recordResponse(response);
 
     if (response.stopReason === "error" || response.stopReason === "aborted") {
       const fallbackMessage =
         response.stopReason === "aborted" ? "Request was aborted." : "Provider returned an error.";
-      return {
-        ok: false,
-        failure: createAutoTitleFailure(trigger, model, response.errorMessage || fallbackMessage),
-      };
+      return failGeneration(run, trigger, model, response.errorMessage || fallbackMessage);
     }
 
     const normalizedTitle = normalizeGeneratedAutoTitle(extractResponseText(response.content));
     if (!normalizedTitle) {
-      return {
-        ok: false,
-        failure: createAutoTitleFailure(trigger, model, "Model returned an empty title."),
-      };
+      return failGeneration(
+        run,
+        trigger,
+        model,
+        describeEmptyTitle(response.stopReason === "length", generation.tokenBudget),
+      );
     }
 
     return {
@@ -102,10 +113,7 @@ export async function generateAutoTitle(
       title: normalizedTitle,
     };
   } catch (error) {
-    return {
-      ok: false,
-      failure: createAutoTitleFailure(trigger, model, extractErrorMessage(error)),
-    };
+    return failGeneration(run, trigger, model, extractErrorMessage(error));
   } finally {
     clearTimeout(timeoutId);
   }
@@ -124,6 +132,27 @@ export function createAutoTitleFailure(
   };
 }
 
+function failGeneration(
+  run: AutoTitleRun | undefined,
+  trigger: AutoTitleTrigger,
+  model: Model<Api>,
+  message: string,
+): AutoTitleGenerationResult {
+  run?.recordFailure(message);
+  return {
+    ok: false,
+    failure: createAutoTitleFailure(trigger, model, message),
+  };
+}
+
+function describeEmptyTitle(hitTokenBudget: boolean, tokenBudget: number): string {
+  if (!hitTokenBudget) {
+    return "Model returned an empty title.";
+  }
+
+  return `Model spent its ${tokenBudget}-token budget without producing a title. Raise sessions.autoTitle.tokenBudget if the model reasons before answering.`;
+}
+
 function buildAutoTitleSystemPrompt(systemPrompt: string, shouldPreserveTitle: boolean): string {
   if (!shouldPreserveTitle) {
     return systemPrompt;
@@ -170,45 +199,6 @@ function normalizeGeneratedAutoTitle(value: string): string | undefined {
   return truncated || undefined;
 }
 
-function writeAutoTitleDebugRequest(
-  model: Model<Api>,
-  trigger: AutoTitleTrigger,
-  request: unknown,
-): void {
-  writeAutoTitleDebugEntry({
-    phase: "request",
-    trigger,
-    model: formatModelLabel(model),
-    request,
-  });
-}
-
-function writeAutoTitleDebugResponse(
-  model: Model<Api>,
-  trigger: AutoTitleTrigger,
-  response: unknown,
-): void {
-  writeAutoTitleDebugEntry({
-    phase: "response",
-    trigger,
-    model: formatModelLabel(model),
-    response,
-  });
-}
-
-function writeAutoTitleDebugEntry(entry: Record<string, unknown>): void {
-  try {
-    const dir = join(homedir(), ".pi", "agent", "pi-sessions");
-    mkdirSync(dir, { recursive: true });
-    appendFileSync(
-      join(dir, "auto-title-debug.jsonl"),
-      `${JSON.stringify({ at: new Date().toISOString(), ...entry })}\n`,
-    );
-  } catch {
-    // Debug logging must not affect title generation.
-  }
-}
-
 function extractResponseText(content: unknown[]): string {
   return content
     .filter(

package/extensions/session-auto-title/install.ts

@@ -53,7 +53,9 @@ export function installAutoTitle(
   ): AutoTitleGeneration => ({
     systemPrompt: settings.autoTitle.prompt,
     timeoutMs: settings.autoTitle.timeoutMs,
+    tokenBudget: settings.autoTitle.tokenBudget,
     thinkingLevel: settings.autoTitle.thinkingLevel ?? resolution?.thinkingLevel,
+    persistRuns: settings.autoTitle.persistRuns,
   });
 
   pi.registerCommand("title", {

package/extensions/session-auto-title/runs.ts

@@ -0,0 +1,50 @@
+import type { ThinkingLevel } from "@earendil-works/pi-agent-core";
+import type { Api, AssistantMessage, Model, UserMessage } from "@earendil-works/pi-ai";
+import { SessionManager } from "@earendil-works/pi-coding-agent";
+import { getDefaultAutoTitleRunsDir } from "../shared/settings.ts";
+import type { AutoTitleTrigger } from "./state.ts";
+
+export const AUTO_TITLE_RUN_REQUEST_CUSTOM_TYPE = "pi-sessions.auto-title-request";
+export const AUTO_TITLE_RUN_FAILURE_CUSTOM_TYPE = "pi-sessions.auto-title-failure";
+
+export interface AutoTitleRunRequest {
+  cwd: string;
+  model: Model<Api>;
+  trigger: AutoTitleTrigger;
+  systemPrompt: string;
+  tokenBudget: number;
+  thinkingLevel: ThinkingLevel | undefined;
+  message: UserMessage;
+}
+
+export interface AutoTitleRun {
+  sessionPath: string | undefined;
+  recordResponse(response: AssistantMessage): void;
+  recordFailure(message: string): void;
+}
+
+/** Records one auto-title request as a standalone Pi session so the exact prompt can be replayed. */
+export function startAutoTitleRun(request: AutoTitleRunRequest): AutoTitleRun {
+  const sessionManager = SessionManager.create(request.cwd, getDefaultAutoTitleRunsDir());
+  sessionManager.appendSessionInfo(`auto-title (${request.trigger})`);
+  sessionManager.appendModelChange(request.model.provider, request.model.id);
+  if (request.thinkingLevel) {
+    sessionManager.appendThinkingLevelChange(request.thinkingLevel);
+  }
+  sessionManager.appendCustomEntry(AUTO_TITLE_RUN_REQUEST_CUSTOM_TYPE, {
+    trigger: request.trigger,
+    systemPrompt: request.systemPrompt,
+    tokenBudget: request.tokenBudget,
+  });
+  sessionManager.appendMessage(request.message);
+
+  return {
+    sessionPath: sessionManager.getSessionFile(),
+    recordResponse(response) {
+      sessionManager.appendMessage(response);
+    },
+    recordFailure(message) {
+      sessionManager.appendCustomEntry(AUTO_TITLE_RUN_FAILURE_CUSTOM_TYPE, { message });
+    },
+  };
+}

package/extensions/session-handoff/kickoff.ts

@@ -55,22 +55,23 @@ export function buildHandoffKickoffSource(source: HandoffKickoffSource): Handoff
   };
 }
 
-export const renderHandoffKickoffMessage: MessageRenderer = (message, _options, theme) => {
+export const renderHandoffKickoffMessage: MessageRenderer = (message, options, theme) => {
   const details = safeParseTypeBoxValue(HANDOFF_KICKOFF_DETAILS_SCHEMA, message.details);
   if (!details) {
     return undefined;
   }
 
   const prompt = typeof message.content === "string" ? message.content : "";
-  return createHandoffKickoffComponent(details, prompt, theme);
+  return createHandoffKickoffComponent(details, prompt, options.outputPad, theme);
 };
 
 export function createHandoffKickoffComponent(
   details: HandoffKickoffDetails,
   prompt: string,
+  outputPad: number,
   theme: RenderTheme,
 ): Component {
-  const box = new Box(1, 1, (text: string) => theme.bg("customMessageBg", text));
+  const box = new Box(outputPad, 1, (text: string) => theme.bg("customMessageBg", text));
   box.addChild(new Text(renderHandoffKickoffView(details, prompt, theme), 0, 0));
   return box;
 }

package/extensions/session-handoff/metadata.ts

@@ -15,7 +15,7 @@ export const HANDOFF_BOOTSTRAP_CONSUMED_CUSTOM_TYPE = "pi-sessions.handoff-boots
 export const HANDOFF_STALE_SESSION_MESSAGE =
   "Session handoff failed: target session already has user input.";
 export const SESSION_STARTING_MESSAGE =
-  "Target session is still starting. wait for it to show up in session_search, then resend.";
+  "Target session is still starting. wait for session_reachable to report it as live, then resend.";
 
 // A subagent's self-knowledge, stamped into its child-local bootstrap so the
 // child never opens the parent transcript to learn who it is.

package/extensions/session-messaging/broker/client-frame.ts

@@ -0,0 +1,113 @@
+// The broker runs as a detached raw-Node process with nothing installed next to
+// it, so client frames are validated by hand rather than against the TypeBox
+// schemas in shared/session-broker/protocol.ts. The broker only routes
+// envelopes, so it validates the routing fields and treats `envelope` as an
+// opaque object; the receiving client validates the envelope body in full.
+
+export interface RoutedEnvelope {
+  [key: string]: unknown;
+}
+
+export interface RegisterClientFrame {
+  type: "register";
+  sessionId: string;
+}
+
+export interface UnregisterClientFrame {
+  type: "unregister";
+}
+
+export interface ListClientFrame {
+  type: "list";
+  requestId: string;
+}
+
+export interface SendClientFrame {
+  type: "send";
+  requestId: string;
+  target: string;
+  envelope: RoutedEnvelope;
+}
+
+export interface IncomingAckClientFrame {
+  type: "incoming_ack";
+  requestId: string;
+  delivered: boolean;
+  error?: string;
+}
+
+export type BrokerClientFrame =
+  | RegisterClientFrame
+  | UnregisterClientFrame
+  | ListClientFrame
+  | SendClientFrame
+  | IncomingAckClientFrame;
+
+const CONTEXT = "Invalid session messaging client frame";
+
+export function parseClientFrame(value: unknown): BrokerClientFrame {
+  const frame = requireObject(value, "/");
+
+  switch (frame.type) {
+    case "register":
+      return { type: "register", sessionId: requireString(frame.sessionId, "/sessionId") };
+    case "unregister":
+      return { type: "unregister" };
+    case "list":
+      return { type: "list", requestId: requireString(frame.requestId, "/requestId") };
+    case "send":
+      return {
+        type: "send",
+        requestId: requireString(frame.requestId, "/requestId"),
+        target: requireString(frame.target, "/target"),
+        envelope: requireObject(frame.envelope, "/envelope"),
+      };
+    case "incoming_ack": {
+      const error = optionalString(frame.error, "/error");
+      return {
+        type: "incoming_ack",
+        requestId: requireString(frame.requestId, "/requestId"),
+        delivered: requireBoolean(frame.delivered, "/delivered"),
+        ...(error === undefined ? {} : { error }),
+      };
+    }
+    default:
+      throw invalid("/type", "expected a known client frame type");
+  }
+}
+
+function requireObject(value: unknown, path: string): Record<string, unknown> {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    throw invalid(path, "expected an object");
+  }
+
+  return value as Record<string, unknown>;
+}
+
+function requireString(value: unknown, path: string): string {
+  if (typeof value !== "string") {
+    throw invalid(path, "expected a string");
+  }
+
+  return value;
+}
+
+function requireBoolean(value: unknown, path: string): boolean {
+  if (typeof value !== "boolean") {
+    throw invalid(path, "expected a boolean");
+  }
+
+  return value;
+}
+
+function optionalString(value: unknown, path: string): string | undefined {
+  if (value === undefined) {
+    return undefined;
+  }
+
+  return requireString(value, path);
+}
+
+function invalid(path: string, message: string): Error {
+  return new Error(`${CONTEXT}: ${path} ${message}`);
+}