@ai-devkit/agent-manager 0.31.0 → 0.33.0

package/src/runtime/ManagedAgentRuntime.ts

@@ -0,0 +1,266 @@
+import type { AgentInfo } from "../adapters/AgentAdapter.js";
+import type { TerminalLocation } from "../terminal/TerminalFocusManager.js";
+import { TmuxManager } from "../terminal/TmuxManager.js";
+import {
+  AgentRegistry,
+  type AgentRuntimeProvider,
+  type RegistryEntry,
+} from "../utils/AgentRegistry.js";
+import { AGENTS, type StartableAgentType } from "../utils/agents.js";
+import { createInteractiveRuntime } from "./RuntimeFactory.js";
+import { DEFAULT_PID_POLL_INTERVAL_MS, DEFAULT_PID_POLL_TIMEOUT_MS } from "./tmux/PidPolling.js";
+import { TmuxAgentRuntime } from "./tmux/TmuxAgentRuntime.js";
+import type { InteractiveAgentRuntime } from "./types.js";
+import {
+  AgentNameInUseError,
+  AgentPidPollTimeoutError,
+  AgentRuntimeUnavailableError,
+  AgentTerminalNotFoundError,
+  TmuxUnavailableError,
+} from "./errors.js";
+
+export {
+  AgentNameInUseError,
+  AgentPidPollTimeoutError,
+  AgentRuntimeUnavailableError,
+  AgentTerminalNotFoundError,
+  TmuxUnavailableError,
+};
+export { DEFAULT_PID_POLL_INTERVAL_MS, DEFAULT_PID_POLL_TIMEOUT_MS };
+
+export interface StartAgentOptions {
+  type: StartableAgentType;
+  name: string;
+  cwd: string;
+  runtimeProvider?: AgentRuntimeProvider;
+  pollIntervalMs?: number;
+  pollTimeoutMs?: number;
+}
+
+export interface StartAgentDeps {
+  tmux?: TmuxManager;
+  runtime?: InteractiveAgentRuntime;
+  registry?: AgentRegistry;
+  /** Called for non-fatal events (e.g., replacing an orphan tmux session). */
+  onWarning?: (message: string) => void;
+}
+
+export interface StopAgentDeps {
+  tmux?: Pick<TmuxManager, "killSession">;
+  runtime?: InteractiveAgentRuntime;
+  registry?: Pick<AgentRegistry, "lookup">;
+  killProcess?: (pid: number, signal: NodeJS.Signals) => void;
+}
+
+export interface StopAgentResult {
+  agentName: string;
+  pid: number;
+  runtime: AgentRuntimeProvider;
+  runtimeRef: unknown | null;
+}
+
+export interface FocusAgentDeps {
+  runtime?: InteractiveAgentRuntime;
+  registry?: Pick<AgentRegistry, "lookup">;
+  focusManager: {
+    findTerminal(pid: number): Promise<TerminalLocation | null>;
+    focusTerminal(location: TerminalLocation): Promise<boolean>;
+  };
+}
+
+export type FocusAgentResult =
+  | { focused: true }
+  | { focused: false; reason: "terminal-not-found" | "focus-failed" };
+
+export interface SendAgentPromptDeps {
+  runtime?: InteractiveAgentRuntime;
+  registry?: Pick<AgentRegistry, "lookup">;
+  focusManager: {
+    findTerminal(pid: number): Promise<TerminalLocation | null>;
+  };
+  writer?: (location: TerminalLocation, text: string) => Promise<void>;
+}
+
+/**
+ * Orchestrate `agent start`: ensure the configured runtime is available,
+ * create the runtime session, detect the agent PID, and register the entry.
+ * Callers are responsible for user input validation before invoking this.
+ */
+export async function startAgent(
+  opts: StartAgentOptions,
+  deps: StartAgentDeps = {},
+): Promise<RegistryEntry> {
+  const registry = deps.registry ?? AgentRegistry.default();
+  const agent = AGENTS[opts.type];
+  const intervalMs = opts.pollIntervalMs ?? DEFAULT_PID_POLL_INTERVAL_MS;
+  const timeoutMs = opts.pollTimeoutMs ?? DEFAULT_PID_POLL_TIMEOUT_MS;
+  const provider = opts.runtimeProvider ?? deps.runtime?.provider ?? "tmux";
+  const tmux = provider === "tmux" ? (deps.tmux ?? new TmuxManager()) : undefined;
+  const runtime = resolveStartRuntime(provider, { ...deps, tmux });
+
+  const availability = await runtime.isAvailable();
+  if (!availability.ok) {
+    if (provider === "tmux") throw new TmuxUnavailableError();
+    throw new AgentRuntimeUnavailableError(provider, availability.reason, availability.detail);
+  }
+
+  registry.prune();
+  const existing = registry.lookup(opts.name);
+  if (existing) {
+    throw new AgentNameInUseError(opts.name, existing.pid);
+  }
+
+  if (provider === "tmux" && tmux && (await tmux.sessionExists(opts.name))) {
+    deps.onWarning?.(
+      `tmux session "${opts.name}" already exists but has no live registry entry — it will be replaced.`,
+    );
+  }
+
+  const result = await runtime.startAgent({
+    name: opts.name,
+    cwd: opts.cwd,
+    kind: agentRuntimeKind(opts.type, provider),
+    args: [],
+    timeoutMs,
+    ...(provider === "tmux"
+      ? {
+          command: agent.command,
+          matches: agent.matches,
+          pollIntervalMs: intervalMs,
+        }
+      : {}),
+  });
+
+  const entry: RegistryEntry = {
+    name: opts.name,
+    type: opts.type,
+    pid: result.pid,
+    runtime: runtime.provider,
+    runtimeRef: result.runtimeRef,
+    cwd: opts.cwd,
+    startedAt: new Date().toISOString(),
+    sessionId: "",
+    sessionFilePath: "",
+    pinned: false,
+  };
+  registry.register(entry);
+  return entry;
+}
+
+export async function stopAgent(
+  agent: Pick<AgentInfo, "name" | "pid">,
+  deps: StopAgentDeps = {},
+): Promise<StopAgentResult> {
+  const registry = deps.registry ?? AgentRegistry.default();
+  const registryEntry = registry.lookup(agent.name);
+  const runtime = resolveRuntimeForEntry(registryEntry, deps);
+  const runtimeRef = registryEntry?.runtimeRef ?? null;
+
+  await runtime.stop({
+    agent,
+    runtimeRef,
+    killProcess: deps.killProcess,
+  });
+
+  return {
+    agentName: agent.name,
+    pid: agent.pid,
+    runtime: runtime.provider,
+    runtimeRef,
+  };
+}
+
+export async function focusAgent(
+  agent: Pick<AgentInfo, "name" | "pid">,
+  deps: FocusAgentDeps,
+): Promise<FocusAgentResult> {
+  const registry = deps.registry ?? AgentRegistry.default();
+  const registryEntry = registry.lookup(agent.name);
+  const runtime = resolveRuntimeForEntry(registryEntry, deps);
+  if (runtime.provider === "tmux") {
+    const location = await deps.focusManager.findTerminal(agent.pid);
+    if (!location) return { focused: false, reason: "terminal-not-found" };
+
+    const focused = await deps.focusManager.focusTerminal(location);
+    return focused ? { focused: true } : { focused: false, reason: "focus-failed" };
+  }
+
+  const focused = await runtime.focus({
+    agent,
+    runtimeRef: registryEntry?.runtimeRef ?? null,
+    focusManager: deps.focusManager,
+  });
+
+  if (focused) return { focused: true };
+  return { focused: false, reason: "focus-failed" };
+}
+
+export async function sendAgentPrompt(
+  agent: Pick<AgentInfo, "name" | "pid">,
+  prompt: string,
+  deps: SendAgentPromptDeps,
+): Promise<void> {
+  const registry = deps.registry ?? AgentRegistry.default();
+  const registryEntry = registry.lookup(agent.name);
+  const runtime = resolveRuntimeForEntry(registryEntry, deps);
+
+  await runtime.send(
+    {
+      agent,
+      runtimeRef: registryEntry?.runtimeRef ?? null,
+      prompt,
+    },
+    {
+      focusManager: deps.focusManager,
+      writer: deps.writer,
+    },
+  );
+}
+
+function resolveStartRuntime(
+  provider: AgentRuntimeProvider,
+  deps: StartAgentDeps,
+): InteractiveAgentRuntime {
+  if (deps.runtime && deps.runtime.provider === provider) {
+    return deps.runtime;
+  }
+  if (provider === "tmux") return new TmuxAgentRuntime(deps.tmux);
+  return createInteractiveRuntime(provider);
+}
+
+function resolveRuntimeForEntry(
+  registryEntry: RegistryEntry | null,
+  deps: { runtime?: InteractiveAgentRuntime; tmux?: Pick<TmuxManager, "killSession"> },
+): InteractiveAgentRuntime {
+  if (isHerdrRegistryEntry(registryEntry)) {
+    return deps.runtime?.provider === "herdr" ? deps.runtime : createInteractiveRuntime("herdr");
+  }
+  if (deps.runtime?.provider === "tmux") return deps.runtime;
+  return deps.tmux
+    ? new TmuxAgentRuntime(deps.tmux as TmuxManager)
+    : createInteractiveRuntime("tmux");
+}
+
+function isHerdrRegistryEntry(
+  entry: unknown,
+): entry is RegistryEntry & { runtime: "herdr"; runtimeRef: unknown } {
+  return (
+    typeof entry === "object" &&
+    entry !== null &&
+    (entry as { runtime?: unknown }).runtime === "herdr" &&
+    "runtimeRef" in entry
+  );
+}
+
+function agentRuntimeKind(type: StartableAgentType, provider: AgentRuntimeProvider): string {
+  if (provider === "tmux") return type;
+  return {
+    claude: "claude",
+    codex: "codex",
+    copilot: "copilot",
+    gemini_cli: "gemini",
+    grok_cli: "grok",
+    opencode: "opencode",
+    pi: "pi",
+  }[type];
+}

package/src/runtime/RuntimeFactory.ts

@@ -0,0 +1,13 @@
+import type { AgentRuntimeProvider } from "../utils/AgentRegistry.js";
+import { HerdrAgentRuntime } from "./herdr/HerdrAgentRuntime.js";
+import { TmuxAgentRuntime } from "./tmux/TmuxAgentRuntime.js";
+import type { InteractiveAgentRuntime } from "./types.js";
+
+function createHerdrRuntime(): InteractiveAgentRuntime {
+  return new HerdrAgentRuntime();
+}
+
+export function createInteractiveRuntime(provider: AgentRuntimeProvider): InteractiveAgentRuntime {
+  if (provider === "herdr") return createHerdrRuntime();
+  return new TmuxAgentRuntime();
+}

package/src/runtime/errors.ts

@@ -0,0 +1,50 @@
+import type { AgentRuntimeProvider } from "../utils/AgentRegistry.js";
+
+export class TmuxUnavailableError extends Error {
+  constructor() {
+    super("tmux is not installed or not in PATH.");
+    this.name = "TmuxUnavailableError";
+  }
+}
+
+export class AgentNameInUseError extends Error {
+  constructor(
+    public agentName: string,
+    public pid: number,
+  ) {
+    super(`Agent "${agentName}" is already running (PID ${pid}).`);
+    this.name = "AgentNameInUseError";
+  }
+}
+
+export class AgentPidPollTimeoutError extends Error {
+  constructor(
+    public agentName: string,
+    public command: string,
+    public timeoutMs: number,
+  ) {
+    super(`Agent process not found after ${timeoutMs / 1000}s.`);
+    this.name = "AgentPidPollTimeoutError";
+  }
+}
+
+export class AgentRuntimeUnavailableError extends Error {
+  constructor(
+    public provider: AgentRuntimeProvider,
+    public reason: string,
+    public detail: string,
+  ) {
+    super(`${provider} runtime is unavailable (${reason}): ${detail}`);
+    this.name = "AgentRuntimeUnavailableError";
+  }
+}
+
+export class AgentTerminalNotFoundError extends Error {
+  constructor(
+    public agentName: string,
+    public pid: number,
+  ) {
+    super(`Cannot find terminal for agent "${agentName}" (PID: ${pid}).`);
+    this.name = "AgentTerminalNotFoundError";
+  }
+}

package/src/runtime/herdr/HerdrAgentRuntime.ts

@@ -0,0 +1,190 @@
+import { HerdrCliClient, isCommandMissing, type HerdrCommandRunner } from "./HerdrCliClient.js";
+import { HerdrRuntimeError } from "./HerdrErrors.js";
+import { parseHerdrRuntimeRef } from "./HerdrRuntimeRef.js";
+import {
+  extractAgentRuntimeRef,
+  extractProcessInfoPid,
+  extractWorkspaceStart,
+} from "./HerdrResponseParsers.js";
+import type {
+  AgentRuntimeAvailability,
+  InteractiveAgentRuntime,
+  RuntimeFocusInput,
+  RuntimeSendInput,
+  RuntimeStartInput,
+  RuntimeStartResult,
+  RuntimeStopInput,
+} from "../types.js";
+
+const AGENT_START_BUSY_RETRY_MS = 5000;
+const AGENT_START_BUSY_RETRY_INTERVAL_MS = 100;
+
+export interface HerdrRuntimeOptions {
+  runner?: HerdrCommandRunner;
+  env?: NodeJS.ProcessEnv;
+  agentStartBusyRetryMs?: number;
+  agentStartBusyRetryIntervalMs?: number;
+}
+
+export class HerdrAgentRuntime implements InteractiveAgentRuntime {
+  readonly provider = "herdr" as const;
+
+  private readonly client: HerdrCliClient;
+  private readonly env: NodeJS.ProcessEnv;
+  private readonly agentStartBusyRetryMs: number;
+  private readonly agentStartBusyRetryIntervalMs: number;
+
+  constructor(options: HerdrRuntimeOptions = {}) {
+    this.client = new HerdrCliClient(options.runner);
+    this.env = options.env ?? process.env;
+    this.agentStartBusyRetryMs = options.agentStartBusyRetryMs ?? AGENT_START_BUSY_RETRY_MS;
+    this.agentStartBusyRetryIntervalMs =
+      options.agentStartBusyRetryIntervalMs ?? AGENT_START_BUSY_RETRY_INTERVAL_MS;
+  }
+
+  async isAvailable(): Promise<AgentRuntimeAvailability> {
+    try {
+      await this.client.run(["--version"]);
+    } catch (error) {
+      if (isCommandMissing(error)) {
+        return {
+          ok: false,
+          reason: "binary-missing",
+          detail: "herdr command was not found in PATH.",
+        };
+      }
+      return {
+        ok: false,
+        reason: "backend-unreachable",
+        detail: (error as Error).message,
+      };
+    }
+
+    try {
+      await this.client.run(["api", "snapshot"]);
+    } catch (error) {
+      return {
+        ok: false,
+        reason: "backend-unreachable",
+        detail: (error as Error).message,
+      };
+    }
+
+    const currentPaneId = nonEmptyString(this.env.HERDR_PANE_ID);
+    return {
+      ok: true,
+      insideRuntime: this.env.HERDR_ENV === "1",
+      ...(currentPaneId ? { currentPaneId } : {}),
+    };
+  }
+
+  async startAgent(input: RuntimeStartInput): Promise<RuntimeStartResult> {
+    const workspace = extractWorkspaceStart(
+      await this.client.runJson(["workspace", "create", "--cwd", input.cwd, "--label", input.name]),
+    );
+
+    const agentResponse = await this.runAgentStartJson([
+      "agent",
+      "start",
+      input.name,
+      "--kind",
+      input.kind,
+      "--pane",
+      workspace.paneId,
+      ...(input.timeoutMs ? ["--timeout", String(input.timeoutMs)] : []),
+      ...(input.args?.length ? ["--", ...input.args] : []),
+    ]);
+    const runtimeRef = extractAgentRuntimeRef(agentResponse, {
+      name: input.name,
+      paneId: workspace.paneId,
+      workspaceId: workspace.workspaceId,
+    });
+    const processInfoResponse = await this.client.runJson([
+      "pane",
+      "process-info",
+      "--pane",
+      runtimeRef.paneId,
+    ]);
+    const pid = extractProcessInfoPid(processInfoResponse);
+    if (pid === null) {
+      throw new HerdrRuntimeError("Herdr pane process-info response did not include process pid.");
+    }
+
+    return { pid, runtimeRef };
+  }
+
+  async send(input: RuntimeSendInput): Promise<void> {
+    const ref = parseHerdrRuntimeRef(input.runtimeRef);
+    await this.client.run(["agent", "prompt", ref.paneId, input.prompt]);
+  }
+
+  async wait(input: { runtimeRef: unknown; timeoutMs: number }): Promise<void> {
+    const ref = parseHerdrRuntimeRef(input.runtimeRef);
+    await this.client.run([
+      "agent",
+      "wait",
+      ref.paneId,
+      "--until",
+      "done",
+      "--until",
+      "blocked",
+      "--timeout",
+      String(input.timeoutMs),
+    ]);
+  }
+
+  async readOutput(input: { runtimeRef: unknown; lines?: number }): Promise<string> {
+    const ref = parseHerdrRuntimeRef(input.runtimeRef);
+    const { stdout } = await this.client.run([
+      "agent",
+      "read",
+      ref.paneId,
+      "--source",
+      "recent-unwrapped",
+      "--lines",
+      String(input.lines ?? 120),
+    ]);
+    return stdout;
+  }
+
+  async focus(input: RuntimeFocusInput): Promise<boolean> {
+    const ref = parseHerdrRuntimeRef(input.runtimeRef);
+    await this.client.run(["agent", "focus", ref.paneId]);
+    return true;
+  }
+
+  async stop(input: RuntimeStopInput): Promise<void> {
+    const ref = parseHerdrRuntimeRef(input.runtimeRef);
+    await this.client.run(["pane", "close", ref.paneId]);
+  }
+
+  private async runAgentStartJson(args: string[]): Promise<unknown> {
+    const deadline = Date.now() + this.agentStartBusyRetryMs;
+    let lastBusyError: HerdrRuntimeError | null = null;
+    do {
+      try {
+        return await this.client.runJson(args);
+      } catch (error) {
+        if (!(error instanceof HerdrRuntimeError) || error.code !== "agent_pane_busy") throw error;
+        lastBusyError = error;
+        if (Date.now() >= deadline) break;
+        await sleep(this.agentStartBusyRetryIntervalMs);
+      }
+    } while (Date.now() < deadline);
+    throw (
+      lastBusyError ??
+      new HerdrRuntimeError("Herdr agent start failed because the target pane stayed busy.", {
+        code: "agent_pane_busy",
+      })
+    );
+  }
+}
+
+function sleep(ms: number): Promise<void> {
+  if (ms <= 0) return Promise.resolve();
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+function nonEmptyString(value: unknown): string | undefined {
+  return typeof value === "string" && value.trim() ? value : undefined;
+}

package/src/runtime/herdr/HerdrCliClient.ts

@@ -0,0 +1,78 @@
+import { execFile } from "child_process";
+import { promisify } from "util";
+import { HerdrRuntimeError } from "./HerdrErrors.js";
+import { herdrErrorFromResponse } from "./HerdrResponseParsers.js";
+
+const execFileAsync = promisify(execFile);
+
+export interface HerdrCommandResult {
+  stdout: string;
+  stderr: string;
+}
+
+export type HerdrCommandRunner = (command: string, args: string[]) => Promise<HerdrCommandResult>;
+
+export class HerdrCliClient {
+  constructor(private readonly runner: HerdrCommandRunner = defaultRunner) {}
+
+  run(args: string[]): Promise<HerdrCommandResult> {
+    return this.runner("herdr", args);
+  }
+
+  async runJson(args: string[]): Promise<unknown> {
+    let stdout: string;
+    try {
+      ({ stdout } = await this.run(args));
+    } catch (error) {
+      throw parseHerdrCommandError(error);
+    }
+    try {
+      const parsed = JSON.parse(stdout) as unknown;
+      const herdrError = herdrErrorFromResponse(parsed);
+      if (herdrError) throw herdrError;
+      return parsed;
+    } catch (error) {
+      if (error instanceof HerdrRuntimeError) throw error;
+      throw new HerdrRuntimeError(`Herdr returned invalid JSON: ${(error as Error).message}`);
+    }
+  }
+}
+
+export function isCommandMissing(error: unknown): boolean {
+  return Boolean(
+    error &&
+    typeof error === "object" &&
+    "code" in error &&
+    (error as NodeJS.ErrnoException).code === "ENOENT",
+  );
+}
+
+function defaultRunner(command: string, args: string[]): Promise<HerdrCommandResult> {
+  return execFileAsync(command, args).then(({ stdout, stderr }) => ({ stdout, stderr }));
+}
+
+function parseHerdrCommandError(error: unknown): HerdrRuntimeError {
+  const stdout =
+    typeof error === "object" && error && "stdout" in error
+      ? String((error as { stdout?: unknown }).stdout ?? "")
+      : "";
+  const stderr =
+    typeof error === "object" && error && "stderr" in error
+      ? String((error as { stderr?: unknown }).stderr ?? "")
+      : "";
+  const parsed = parseJson(stdout) ?? parseJson(stderr);
+  if (parsed) {
+    const herdrError = herdrErrorFromResponse(parsed);
+    if (herdrError) return herdrError;
+  }
+  return new HerdrRuntimeError((error as Error).message);
+}
+
+function parseJson(value: string): unknown | null {
+  if (!value.trim()) return null;
+  try {
+    return JSON.parse(value) as unknown;
+  } catch {
+    return null;
+  }
+}

package/src/runtime/herdr/HerdrErrors.ts

@@ -0,0 +1,9 @@
+export class HerdrRuntimeError extends Error {
+  readonly code?: string;
+
+  constructor(message: string, options: { code?: string } = {}) {
+    super(message);
+    this.name = "HerdrRuntimeError";
+    this.code = options.code;
+  }
+}

package/src/runtime/herdr/HerdrResponseParsers.ts

@@ -0,0 +1,76 @@
+import { HerdrRuntimeError } from "./HerdrErrors.js";
+import type { HerdrRuntimeRef } from "./HerdrRuntimeRef.js";
+
+export function extractWorkspaceStart(value: unknown): { workspaceId?: string; paneId: string } {
+  const workspaceId = getString(value, ["result", "workspace", "workspace_id"]);
+  const paneId = getString(value, ["result", "root_pane", "pane_id"]);
+  if (!paneId) {
+    throw new HerdrRuntimeError("Herdr workspace create response did not include root pane id.");
+  }
+  return {
+    ...(workspaceId ? { workspaceId } : {}),
+    paneId,
+  };
+}
+
+export function extractAgentRuntimeRef(
+  value: unknown,
+  fallback: { paneId: string; name: string; workspaceId?: string },
+): HerdrRuntimeRef {
+  const agentPaneId = getString(value, ["result", "agent", "pane_id"]) ?? fallback.paneId;
+  const agentName = getString(value, ["result", "agent", "name"]) ?? fallback.name;
+  const tabId = getString(value, ["result", "agent", "tab_id"]);
+  return {
+    session: "default",
+    ...(fallback.workspaceId ? { workspaceId: fallback.workspaceId } : {}),
+    ...(tabId ? { tabId } : {}),
+    paneId: agentPaneId,
+    agentName,
+  };
+}
+
+export function extractProcessInfoPid(value: unknown): number | null {
+  const processInfo = getObject(value, ["result", "process_info"]);
+  if (!processInfo) return null;
+  const processes = processInfo.foreground_processes;
+  if (!Array.isArray(processes)) return numberOrNull(processInfo.shell_pid);
+  for (const processInfo of processes) {
+    if (!processInfo || typeof processInfo !== "object") continue;
+    const pid = numberOrNull((processInfo as { pid?: unknown }).pid);
+    if (pid !== null) return pid;
+  }
+  return numberOrNull(processInfo.shell_pid);
+}
+
+export function herdrErrorFromResponse(value: unknown): HerdrRuntimeError | null {
+  const error = getObject(value, ["error"]);
+  if (!error) return null;
+  const message = nonEmptyString(error.message) ?? "Herdr command failed.";
+  const code = nonEmptyString(error.code);
+  return new HerdrRuntimeError(message, code ? { code } : {});
+}
+
+function getObject(value: unknown, path: string[]): Record<string, unknown> | null {
+  let current = value;
+  for (const part of path) {
+    if (!current || typeof current !== "object" || Array.isArray(current) || !(part in current))
+      return null;
+    current = (current as Record<string, unknown>)[part];
+  }
+  return current && typeof current === "object" && !Array.isArray(current)
+    ? (current as Record<string, unknown>)
+    : null;
+}
+
+function getString(value: unknown, path: string[]): string | undefined {
+  const parent = getObject(value, path.slice(0, -1));
+  return parent ? nonEmptyString(parent[path[path.length - 1]!]) : undefined;
+}
+
+function nonEmptyString(value: unknown): string | undefined {
+  return typeof value === "string" && value.trim() ? value : undefined;
+}
+
+function numberOrNull(value: unknown): number | null {
+  return typeof value === "number" && Number.isInteger(value) && value > 0 ? value : null;
+}