transcribe / analyzeImage — media ports

Two tools — speech-to-text and image understanding — built on the exact same ports pattern you've now seen six times. Each is a tiny dispatch kernel: validate the request (Zod), call the injected backend, re-validate the untrusted result (Zod), return a Result. The production backends are dependency-free fetch impls. This lesson is the closing proof that the discipline scales: a new capability is a port plus a kernel plus a thin fetch seam — nothing more. A CLONE of Hermes' transcription_tools.py (1799 LOC) + vision_tools.py, CLOUD path only.

Two backends, two kernels, one shape

Each tool's network call becomes an injected port — a single function returning a Result. The module imports no SDK:

// packages/hermes/src/media/types.ts:133-148
export type TranscriptionBackend = (
  req: TranscriptionRequest,
) => Promise<Result<TranscriptionResult, Error>>;

export type VisionBackend = (
  req: VisionRequest,
) => Promise<Result<VisionResult, Error>>;

// packages/hermes/src/media/media.ts:51-68 — transcribe
const parsedReq = transcriptionRequestSchema.safeParse(req);
if (!parsedReq.success) return err(new Error(`Invalid transcription request: …`));
const transcribed = await deps.backend(parsedReq.data);
if (!transcribed.ok) return transcribed;          // backend failure ⇒ err
const parsed = transcriptionResultSchema.safeParse(transcribed.value);
if (!parsed.success) return err(new Error(`Invalid transcription result: …`)); // untrusted out
return ok(parsed.data);

analyzeImage is byte-for-byte the same shape (validate request → backend → validate result), differing only in the schemas. That symmetry is the lesson: once the pattern is established, a new media tool is mechanical.

Cross-field validation: exactly one audio source

The transcription request models a portable audio source — a URL the backend fetches, or inline base64 — and enforces "exactly one" with a Zod refinement (an XOR over the two optionals):

// packages/hermes/src/media/types.ts:62-74 — transcriptionRequestSchema
z.object({
  audioUrl: z.string().url('audioUrl must be a valid URL').optional(),
  audioBase64: z.string().min(1, 'audioBase64 cannot be empty').optional(),
  mimeType: z.string().min(1).optional(),
}).refine(
  (req) => (req.audioUrl === undefined) !== (req.audioBase64 === undefined),
  { message: 'exactly one of audioUrl or audioBase64 is required' },
);

The !== over two === undefined checks is a boolean XOR: true only when exactly one source is present. Two tests pin both failure modes — neither source, and both sources, are each rejected at the boundary before the backend is ever called.

The fetch backends — defensive mapping, field fallbacks

Like the web backend, the media backends are thin fetch impls over the global fetch, with defensive payload mapping and field fallbacks. The kernel re-validates, so the mapper can be forgiving:

// packages/hermes/src/media/fetch-backends.ts:163-178 — defensive row mapping
const mapTranscriptionRow = (payload) => {
  const provider = readField(payload, 'provider');
  return {
    text: asString(readField(payload, 'text') ?? readField(payload, 'transcript')), // fallback
    ...(typeof provider === 'string' && provider.length > 0 ? { provider } : {}),
  };
};
const mapVisionRow = (payload) => ({
  analysis: asString(readField(payload, 'analysis') ?? readField(payload, 'content')), // fallback
});

Common confusions