hex/site/public/docs/transforms.md

8.8 KiB
Raw Permalink Blame History

Hex transforms

Transforms are JavaScript or TypeScript functions that change dictated text before Hex pastes it. This page is written for coding agents; it is the whole API. Served at https://anoma.ly/hex/docs/transforms.

Where they live

  • The config is ~/.config/hex/hex.config.ts (or hex.config.js; keep one). Run hex commands init to create it with hex.d.ts (types), AGENTS.md, and tsconfig.json. Typecheck with npx -y -p typescript tsc in that folder.
  • Hex runs it in an embedded JavaScript engine (QuickJS, ES2023 modules) and reloads it about a third of a second after a file in the folder changes. A config that fails to load keeps the previous one; the error shows in Hex.
  • TypeScript works by erasing types. Enums, namespaces, constructor parameter properties, and import x = require() are rejected.
  • Imports: @hex/commands, node:child_process, node:util, and files in the folder by relative path (./lib.ts, ./data.json). No npm packages. Imports load with the config; dynamic import() later is refused.
  • A transform runs only where the person selects it: Hex's Output pane lists the steps, and hex settings set dictation_processing.default_mode '<json>' (or dictation_processing.modes) chooses them by id.

Config shape

import { defineHexConfig } from "@hex/commands"

export default defineHexConfig({
  transformations: {
    "trim-whitespace": {
      name: "Trim whitespace",          // shown in Hex
      description: "Remove leading and trailing whitespace",
      timeout: 1000,                    // optional, milliseconds, 1 to 60000
      transform: (text, context) => text.trim(),
    },
  },
})

transform(text, context) returns a string or a promise of one. context describes the foreground app, each field present only when known:

{ application?: string, browserHost?: string, browserUrl?: string, windowTitle?: string, source?: 'dictation' | 'typed-text' }

source is "dictation" for spoken dictation and "typed-text" for Labs › Transform typed text (Linux), which runs the same steps on text already typed.

Selected transforms run in order after the mode's word replacements and optional AI rewrite. Don't reuse the built-in ids lowercase, spongebob-case, or no-trailing-punctuation.

What a script has

  • Plain JavaScript built-ins, console.log (to Hex's log), setTimeout, clearTimeout, queueMicrotask, AbortController, AbortSignal (abort, timeout, any), and DOMException.
  • fetch, Headers, and Response (below).
  • node:child_process (exec, execFile) and node:util (promisify).
  • No filesystem, environment, process, require, setInterval, URL, TextEncoder, FormData, Blob, or streams. Read files with a program through execFile if you must.
  • 64 MiB of memory for the config.

fetch

The WHATWG shape, with a subset:

const response = await fetch(url, { method, headers, body, signal })
response.ok; response.status; response.statusText; response.url
response.headers.get(name); response.headers.has(name); [...response.headers.entries()]
await response.text(); await response.json(); await response.arrayBuffer()
  • url is an absolute http: or https: URL. Redirects are followed.
  • body is a string (JSON.stringify(...) for JSON); not allowed with GET or HEAD. A string body without a content-type header gets text/plain;charset=UTF-8.
  • headers is an object, an array of pairs, or Headers.
  • The response is read whole before fetch resolves (16 MiB at most); there is no streaming, FormData, or Blob.
  • HTTP error statuses resolve normally (response.ok is false). Network errors reject with TypeError: fetch failed: …; an aborted signal rejects with its reason (AbortError, or TimeoutError for AbortSignal.timeout).
  • TLS uses the operating system's certificates.

Example, a local model through Ollama:

import { defineHexConfig } from "@hex/commands"

export default defineHexConfig({
  transformations: {
    "ollama-tidy": {
      name: "Tidy with Ollama",
      timeout: 20000,
      transform: async (text) => {
        const response = await fetch("http://localhost:11434/api/generate", {
          method: "POST",
          headers: { "content-type": "application/json" },
          body: JSON.stringify({
            model: "llama3.2",
            prompt: `Fix punctuation and capitalization. Reply with the text only.\n\n${text}`,
            stream: false,
          }),
        })
        if (!response.ok) throw new Error(`Ollama answered ${response.status}`)
        const data: { response: string } = await response.json()
        return data.response.trim()
      },
    },
  },
})

node:child_process

Node's exec and execFile, with callbacks and util.promisify:

import { exec, execFile } from "node:child_process"
import { promisify } from "node:util"

const run = promisify(execFile)                         // resolves { stdout, stderr }
const { stdout } = await run("pandoc", ["-t", "plain"], { input: text })
execFile(file, args, options, (error, stdout, stderr) => {})
exec(command, options, (error, stdout, stderr) => {})
  • execFile(file, args, options, callback) runs the program with an argument array and no shell. Use it for anything involving dictated text; never build a shell command out of the text.
  • exec(command, options, callback) runs /bin/sh -c command on macOS and Linux, cmd.exe /d /s /c "command" on Windows, as Node does.
  • Options: cwd (default: the config folder), env (added to a minimal environment of PATH, HOME, user, locale, and temp variables; Hex's own environment is not passed on; on macOS PATH also has /opt/homebrew/bin and /usr/local/bin), timeout (ms, then SIGTERM), maxBuffer (bytes per stream, default 1 MiB, at most 16 MiB), signal, and Hex's addition input: a string written to stdin, which is then closed. Without input, stdin is empty.
  • stdout and stderr are strings (UTF-8). There is no encoding, shell, uid, killSignal, spawn, fork, or sync variants.
  • Errors follow Node: a non-zero exit gives Error: Command failed: <cmd> with code (exit code), killed, signal, and cmd; a missing program gives code: "ENOENT"; a timeout gives killed: true, signal: "SIGTERM"; too much output gives a RangeError with code: "ERR_CHILD_PROCESS_STDIO_MAXBUFFER"; an aborted signal gives an AbortError. Promisified errors also carry stdout and stderr.
  • The returned child has only kill() (SIGTERM to the program and its children) and killed; there is no pid or stream access.

Example, piping the text through a script:

import { defineHexConfig } from "@hex/commands"
import { execFile } from "node:child_process"
import { promisify } from "node:util"

const run = promisify(execFile)

export default defineHexConfig({
  transformations: {
    "house-style": {
      name: "House style",
      transform: async (text) => {
        const { stdout } = await run("python3", ["./house_style.py"], { input: text })
        return stdout.trimEnd()
      },
    },
  },
})

Trust prompt

The first time a config uses fetch or node:child_process, Hex asks the person in its Output pane, listing the hosts and programs it can see written literally in the source (fetch("https://…"), execFile("pandoc", …)), otherwise just the capability. The approval is pinned to a hash of every file the config loaded: any edit asks again. Until it is allowed, fetch rejects and exec/execFile call back with an error saying so, and the transform falls back. A config can't approve itself; the approval is stored in Hex's own data folder.

On a managed Mac, an organization can turn transforms off (DisableTransforms) or keep fetch on this computer with no programs (RestrictTransformsToLoopback); see https://anoma.ly/hex/docs/admin.

Timeouts, limits, and fallback

  • Each transform has timeout milliseconds: 1000 by default, 30000 when the config uses fetch or node:child_process, 60000 at most. That limit covers everything the transform waits for.
  • When a transform finishes or runs out of time, Hex abandons its requests and ends every program it started, with the program's children (a process group on macOS and Linux, a job object on Windows). Quitting Hex does the same. Fire-and-forget work does not outlive the transform.
  • At most 8 requests and 4 programs run at once; more wait their turn.
  • If a transform throws, returns something other than a string, or runs out of time, Hex pastes the text it had before the transforms and logs why. It never blocks dictation; the microphone keeps working while it waits.
  • Input and output text are each limited to 48 KiB.
  • Hex logs the host or program, status or exit code, duration, and byte counts, never the text, request or response bodies, arguments, or environment values.