@op1/threads 0.1.7 → 0.2.0

package/skills/workflow-authoring/references/runtime.md

@@ -0,0 +1,87 @@
+# Workflow runtime contract
+
+Scripts run in OpenCode's confined Code Mode interpreter inside a terminable Bun worker. The parent service enforces the deadline, including during synchronous script work. Scripts cannot import modules or use host filesystem, process, network, clock, or randomness APIs. Agents inspect the outside world and return recorded data. Use arguments for timestamps and other variable inputs.
+
+Keep each result below 1 MiB and the combined run journal below 16 MiB. Payload admission reserves space for control metadata and bounded failure diagnostics, so usable payload capacity is lower. Return concise structured findings and artifact paths instead of complete file contents. Run lists and completion notifications omit the full result; inspect a run to read it.
+
+## Script shape
+
+The first statement is `export const meta = { name: "name", description: "description" }`. Metadata contains literal values. An optional `phases` array contains objects with a `title`.
+
+The body supports top-level `await`, ordinary data transformations, branching, and bounded loops. Return a JSON value. Intermediate agent results stay in script variables and the durable journal.
+
+## Agent steps
+
+`await agent(prompt, options)` returns the validated `result` submitted by its worker. Options are:
+
+| Field | Meaning |
+| --- | --- |
+| `key` | Required unique, stable step name. Include the item and round when using loops. |
+| `agent` | Required configured OpenCode agent ID. |
+| `label` | Optional display title. |
+| `phase` | Optional phase override. |
+| `schema` | Optional JSON Schema for the result. Invalid schemas fail before dispatch. |
+| `access` | `read` by default: only the profile's permitted read, glob, grep, webfetch, websearch, and skill tools. `write` permits the selected profile's other tools. |
+| `isolation` | `shared` by default, or `worktree` for a retained isolated checkout. Creating a worktree requires `access: "write"`; later readers can use its returned `directory`. |
+| `directory` | Optional existing directory inside the owner project or one of its registered worktrees. Symlinks are resolved before containment checks. |
+| `timeoutMs` | Optional step timeout, bounded by the run's execution policy. |
+
+Workers submit `workflows_result({ verdict, summary, evidence, result })`. Invalid results return a validation error so the worker can repair its output. A native execution that ends without a result has no task verdict.
+
+Profile restrictions and the coordinator's restrictions still apply. Read access blocks other plugin and MCP tools, including those with side effects, even if the selected profile permits them. Workflow workers cannot delegate. Selecting `access: "write"` does not grant permissions that the selected profile lacks.
+
+## Composition
+
+- `parallel(thunks)` runs async functions concurrently and returns results in input order.
+- `pipeline(items, ...stages)` runs each item through its stages independently. A fast item does not wait for slower items between stages.
+- `await phase(title)` records a display phase.
+- `await log(message)` records a bounded progress message.
+- `workflow(name, args)` invokes a saved workflow within the parent's limits.
+- `retry(thunk, { attempts })` bounds logical or validation retries, with three attempts by default. Give each agent attempt a distinct step key. Return expected negative findings as validated data, then let the validator decide whether another attempt is useful. A native execution failure or an explicit `FAIL`/`INCONCLUSIVE` report remains an unresolved failure and prevents the run from passing, even when caught by the script. Inspect uncertain writes before starting a replacement run.
+- `gate(thunk, validator, { attempts })` repeats until the validator accepts or attempts run out, with three attempts by default. The validator returns a boolean or `{ ok: boolean, feedback?: string }`. A truthy object without `ok: true` does not pass.
+- `loopUntilDry({ round, key, consecutiveEmpty, maxRounds })` accumulates unique findings until discovery stops producing new items. `round` and `key` are required; `key` is a property name or identity function. Defaults are two consecutive empty rounds and ten maximum rounds. Reaching the maximum returns the accumulated findings.
+- `checkpoint(prompt, { key })` records a question and waits for an explicit response through the run controls. The response becomes recorded input on resume. Responses are limited to 1 MiB and must fit in the aggregate journal. Rejected responses leave the checkpoint unanswered so a smaller response can be submitted.
+
+Errors remain errors unless the script explicitly handles them. Do not discard failed items or substitute a passing result for missing evidence.
+
+## Start and control
+
+`workflows_start` accepts exactly one of `script` or saved `name`, plus a unique task `key`, optional JSON `args`, and limits:
+
+| Limit | Default | Range |
+| --- | --- | --- |
+| `concurrency` | 3 | 1–8 |
+| `maxAgents` | 4 | 1–1000 |
+| `agentTimeoutMs` | 30 minutes | 1 second–7 days |
+| `timeoutMs` | 24 hours | 1 second–7 days |
+| `tokenBudget` | Unset | Positive integer |
+
+The plugin options `workflowConcurrency` and `workflowMaxAgents` override the default concurrency and total agent-step limit for new runs. The registered `workflows_start` schema advertises the configured defaults. Explicit run values override them, and existing runs retain their recorded limits. To use eight concurrent agents, the total agent-step limit must also be at least eight.
+
+`tokenBudget` measures cumulative native input and output tokens across worker turns. It is an admission threshold, not a hard generation cap: workers already running can exceed it before the next dispatch checks their usage. Multi-turn code investigation can consume much more than the final answer's token count. Choose the threshold for the whole run, including review steps, or omit it and use the agent and time limits.
+
+The cumulative host-call cap is `maxAgents * 8 + 100`, including agent, phase, log, checkpoint, and nested-workflow calls. Nested saved workflows share that cap and the parent agent budget. Nesting is limited to four child levels.
+
+Helper bounds (`attempts`, `maxRounds`, and `consecutiveEmpty`) must be safe positive integers no greater than 1,000. Arguments, host-call payloads, and results are each limited to 1 MiB; error diagnostics are capped at 8 KiB. The runtime module allows 64 simultaneous interpreter calls, including nested calls, and rejects excess calls immediately. This is separate from the agent concurrency limit.
+
+The configured Threads worker limit also applies across simultaneous runs owned by one coordinator. Its default is four workers. A token budget checks recorded usage at dispatch, including failed and interrupted attempts. Already-running agents can exceed the remaining budget. Unreported usage is marked unmeasured and blocks further budgeted dispatch.
+
+The same start key and identical input identify the same run. Start retries do not restart completed or stopped runs. Pause stops new scheduling and drains active steps. Stop interrupts active work. Resume uses the same recorded script and arguments, reconciles existing sessions, and reuses completed results. A changed step request under an existing key fails rather than returning a stale result. Save edits as a new workflow run.
+
+A service restart leaves interrupted work available for explicit resume. Worktrees and session evidence are retained. A missing result after an interrupted write requires inspection; it does not prove that no write occurred.
+
+For an uncertain write, inspect its retained worker and directory. Use `threads_send` to ask that same worker to verify the existing effects and submit `workflows_result` without repeating completed actions. After its native execution finishes, resume the workflow. A missing worker session is not permission to replay its writes in a new session.
+
+Nested saved scripts are pinned to their run. Agent successes, exposed failures, and checkpoint responses replay in their original settlement order. An exposed failure cannot become a success during replay. If a selected profile's model, instructions, or permissions change, start a new run rather than treating its old result as evidence from the new profile.
+
+Legacy journals without checkpoint settlement order cannot deterministically resume an answered checkpoint. Such runs fail with a diagnostic and require a new run key. A corrupt or already-full legacy record remains preserved and produces an owner-visible diagnostic without blocking healthy sibling runs. An exact-limit legacy record may need explicit repair before any further control metadata fits.
+
+Checkpoint responses are stored in both checkpoint state and settlement order, so their bytes count twice toward the journal limit. A run too full to accept a response remains unanswered; use a smaller response or a new run key. An inconsistent settlement order may wait until the configured run deadline.
+
+## Saved workflows
+
+`workflows_save` writes a run's script to `.opencode/workflows/<name>.js` in the current directory or to `workflows/<name>.js` under the user's OpenCode configuration. Existing files are not overwritten. Project workflows take precedence over user workflows of the same name.
+
+Use `workflows_saved` to list scripts and `/workflow-<name>` to ask the agent to invoke one with arguments. `/workflow-run <task>` asks the current agent to author a workflow. `/workflows` opens the terminal run navigator.
+
+After editing saved files directly, use `/workflow-refresh` to reload their commands. The saved names `run` and `refresh` are reserved for built-in workflow commands.

package/src/activity-model.ts

@@ -0,0 +1,152 @@
+export type ActivityItem = {
+  id: string;
+  title: string;
+  subtitle: string;
+  updated: number;
+  active: boolean;
+  attention: boolean;
+  busy: boolean;
+  unread?: "activity" | "error";
+  pinned: boolean;
+  hidden: boolean;
+  open: boolean;
+  coordinatorID?: string;
+};
+
+export type ActivityThread = {
+  item: ActivityItem;
+  children: ActivityItem[];
+  status: Pick<ActivityItem, "attention" | "busy" | "unread">;
+};
+
+export function cleanRoleTitle(title: string, managed: boolean) {
+  if (!managed) return title;
+  const remainder = title.replace(/^\[(?:Main|Worker)\] /, "");
+  return remainder.trim() ? remainder : title;
+}
+
+export function activityTime(time: {
+  idle?: number;
+  updated: number;
+  created: number;
+}) {
+  return time.idle ?? time.updated ?? time.created;
+}
+
+export function activitySubtitle(input: {
+  directory: string;
+  project?: { name?: string; canonical: string };
+  role?: "Main" | "Worker";
+}) {
+  const folder = (path: string) =>
+    path
+      .replace(/[\\/]+$/, "")
+      .split(/[\\/]/)
+      .pop() || path;
+  const location = folder(input.directory);
+  const project =
+    input.project?.name?.trim() ||
+    (input.project ? folder(input.project.canonical) : location);
+  const parts = [project];
+  if (input.role) parts.push(input.role);
+  if (
+    input.project &&
+    input.project.canonical !== input.directory &&
+    location !== project
+  )
+    parts.push(location);
+  return parts.join(" · ");
+}
+
+export function dateGroup(timestamp: number, now = new Date()) {
+  const date = new Date(timestamp);
+  const day = (value: Date) =>
+    Date.UTC(value.getFullYear(), value.getMonth(), value.getDate());
+  const age = (day(now) - day(date)) / 86400000;
+  if (age === 0) return "Today";
+  if (age === 1) return "Yesterday";
+  if (age > 1 && age < 7)
+    return date.toLocaleDateString(undefined, { weekday: "long" });
+  return date.toLocaleDateString(undefined, {
+    year: "numeric",
+    month: "short",
+    day: "numeric",
+  });
+}
+
+export function priority(item: ActivityItem) {
+  return item.attention ? 3 : item.busy ? 2 : item.unread ? 1 : 0;
+}
+
+function visible(item: ActivityItem) {
+  return !item.hidden || item.open || item.active || item.busy || item.attention;
+}
+
+function compare(a: ActivityItem, b: ActivityItem) {
+  return (
+    priority(b) - priority(a) ||
+    Number(b.pinned) - Number(a.pinned) ||
+    b.updated - a.updated ||
+    a.id.localeCompare(b.id)
+  );
+}
+
+export function activityGroups(items: ActivityItem[], now = new Date()) {
+  const groups = new Map<string, ActivityItem[]>();
+  const ordered = items.filter(visible).sort(compare);
+  for (const item of ordered) {
+    const key = priority(item)
+      ? "Priority"
+      : item.pinned
+        ? "Pinned"
+        : dateGroup(item.updated, now);
+    const group = groups.get(key) ?? [];
+    group.push(item);
+    groups.set(key, group);
+  }
+  return groups;
+}
+
+export function activityThreads(items: ActivityItem[], now = new Date()) {
+  const available = new Map(items.filter(visible).map((item) => [item.id, item]));
+  const children = new Map<string, ActivityItem[]>();
+  const roots: ActivityItem[] = [];
+  for (const item of available.values()) {
+    const parent = item.coordinatorID
+      ? available.get(item.coordinatorID)
+      : undefined;
+    if (parent && parent.id !== item.id && !parent.coordinatorID) {
+      const siblings = children.get(parent.id) ?? [];
+      siblings.push(item);
+      children.set(parent.id, siblings);
+    } else roots.push(item);
+  }
+  const threads = new Map<string, ActivityThread>();
+  const summaries = roots.map((item) => {
+    const workers = (children.get(item.id) ?? []).sort(compare);
+    const members = [item, ...workers];
+    const status = {
+      attention: members.some((member) => member.attention),
+      busy: members.some((member) => member.busy),
+      unread: members.some((member) => member.unread === "error")
+        ? ("error" as const)
+        : members.find((member) => member.unread)?.unread,
+    };
+    threads.set(item.id, { item, children: workers, status });
+    return {
+      ...item,
+      ...status,
+      pinned: members.some((member) => member.pinned),
+      updated: Math.max(...members.map((member) => member.updated)),
+    };
+  });
+  return new Map(
+    [...activityGroups(summaries, now)].map(([name, group]) => [
+      name,
+      group.flatMap((item) => {
+        const thread = threads.get(item.id);
+        return thread ? [thread] : [];
+      }),
+    ]),
+  );
+}

package/src/activity-picker.tsx

@@ -0,0 +1,175 @@
+import type { Plugin } from "@opencode/plugin/tui";
+import type { InputRenderable, RGBA, ScrollBoxRenderable } from "@opentui/core";
+import { createEffect, createMemo, createSignal, For, onCleanup, Show } from "solid-js";
+import fuzzysort from "fuzzysort";
+import type { ActivityItem } from "./activity-model";
+import { themeColor, themeMuted } from "./activity-theme";
+
+type Choice = Pick<ActivityItem, "id" | "title" | "subtitle" | "pinned"> & {
+  category: string;
+  closed: boolean;
+};
+
+export function ActivityPicker(props: {
+  ctx: Plugin.Context;
+  fallbackColor: RGBA;
+  items: () => Choice[];
+  current: string | undefined;
+  pin: (id: string) => Promise<void>;
+  open: (id: string) => Promise<void>;
+}) {
+  const { ctx } = props;
+  const [query, setQuery] = createSignal("");
+  const [selectedID, setSelectedID] = createSignal(props.current);
+  const [pinning, setPinning] = createSignal(false);
+  const [height, setHeight] = createSignal(ctx.renderer.height);
+  let input: InputRenderable | undefined;
+  let scroll: ScrollBoxRenderable | undefined;
+  let closed = false;
+  const foreground = () => themeColor(ctx.theme.text, props.fallbackColor);
+  const muted = () => themeMuted(ctx.theme.text, foreground());
+  const grouped = createMemo(() => {
+    const items = query()
+      ? fuzzysort.go(query(), props.items(), {
+          keys: ["title", "category"],
+          scoreFn: (result) => result[0].score * 2 + result[1].score,
+        }).map((result) => result.obj)
+      : props.items();
+    const groups = new Map<string, Choice[]>();
+    for (const item of items) {
+      const group = groups.get(item.category) ?? [];
+      group.push(item);
+      groups.set(item.category, group);
+    }
+    return [...groups];
+  });
+  const choices = createMemo(() => grouped().flatMap(([, items]) => items));
+  const selected = () =>
+    choices().find((item) => item.id === selectedID()) ?? choices()[0];
+  const select = (index: number) => setSelectedID(choices()[index]?.id);
+  const move = (direction: number) => {
+    const items = choices();
+    if (!items.length) return;
+    const index = items.findIndex((item) => item.id === selected()?.id);
+    select((index + direction % items.length + items.length) % items.length);
+  };
+  const open = (id = selected()?.id) => {
+    if (!id) return;
+    ctx.ui.dialog.clear();
+    void props.open(id);
+  };
+  const togglePin = async () => {
+    const item = selected();
+    if (!item || pinning()) return;
+    setSelectedID(item.id);
+    setPinning(true);
+    try {
+      await props.pin(item.id);
+    } finally {
+      if (!closed) setPinning(false);
+    }
+  };
+  ctx.keymap.layer(() => ({
+    mode: "global",
+    target: () => input,
+    priority: 100,
+    commands: [
+      { bind: "up", run: () => move(-1) },
+      { bind: "ctrl+p", run: () => move(-1) },
+      { bind: "down", run: () => move(1) },
+      { bind: "ctrl+n", run: () => move(1) },
+      { bind: "pageup", run: () => move(-10) },
+      { bind: "pagedown", run: () => move(10) },
+      { bind: "home", run: () => { select(0); } },
+      { bind: "end", run: () => { select(choices().length - 1); } },
+      { bind: "return", run: () => open() },
+      { bind: "escape", run: () => ctx.ui.dialog.clear() },
+      {
+        id: "threads.activity.choose.pin",
+        title: "Pin/unpin highlighted Activity conversation",
+        bind: "ctrl+f",
+        run: togglePin,
+      },
+    ],
+  }));
+  let scrollTo: string | undefined;
+  createEffect(() => {
+    grouped();
+    scrollTo = selected()?.id;
+  });
+  const reveal = () => {
+    if (!scrollTo || !scroll) return;
+    scroll.scrollChildIntoView(`activity-picker-row-${scrollTo}`);
+    scrollTo = undefined;
+  };
+  const resize = () => setHeight(ctx.renderer.height);
+  ctx.renderer.addPostProcessFn(reveal);
+  ctx.renderer.on("resize", resize);
+  onCleanup(() => {
+    closed = true;
+    ctx.renderer.removePostProcessFn(reveal);
+    ctx.renderer.off("resize", resize);
+  });
+  return (
+    <box id="activity-picker" paddingX={2} paddingY={1} gap={1}>
+      <text fg={foreground()}><b>Activity</b></text>
+      <input
+        id="activity-picker-search"
+        ref={(node) => { input = node; }}
+        focused
+        placeholder="Search"
+        textColor={foreground()}
+        focusedTextColor={foreground()}
+        onInput={(value) => {
+          setQuery(value);
+          setSelectedID(undefined);
+        }}
+      />
+      <scrollbox
+        ref={(node) => { scroll = node; }}
+        height={Math.max(1, Math.min(
+          choices().length + grouped().length * 2,
+          Math.floor(height() / 2) - 6,
+        ))}
+        scrollX={false}
+        scrollbarOptions={{ visible: false }}
+      >
+        <For each={grouped()}>{([category, items]) => <>
+          <text fg={muted()} marginTop={1}>{category}</text>
+          <For each={items}>{(item) => (
+            <box
+              id={`activity-picker-row-${item.id}`}
+              height={1}
+              flexShrink={0}
+              flexDirection="row"
+              backgroundColor={selected()?.id === item.id
+                ? ctx.theme.background.raised?.high ?? themeColor(ctx.theme.background, props.fallbackColor)
+                : undefined}
+              onMouseUp={(event) => {
+                event.stopPropagation();
+                if (event.button === 0) open(item.id);
+              }}
+            >
+              <text
+                id={`activity-picker-title-${item.id}`}
+                fg={foreground()}
+                width="60%"
+                wrapMode="none"
+                truncate
+              >{`${selected()?.id === item.id ? ">" : " "} ${item.pinned ? "◆" : "◇"} ${item.title}`}</text>
+              <text fg={muted()} flexGrow={1} flexShrink={1} minWidth={0} wrapMode="none" truncate>
+                {`${item.subtitle}${item.closed ? " · Closed" : ""}`}
+              </text>
+            </box>
+          )}</For>
+        </>}</For>
+        <Show when={!choices().length}>
+          <text fg={muted()}>No matching conversations</text>
+        </Show>
+      </scrollbox>
+      <text id="activity-picker-hint" fg={muted()}>
+        {`${ctx.keymap.shortcuts("threads.activity.choose.pin").join(" / ")} ${selected()?.pinned ? "Unpin" : "Pin"} · enter Open · esc Close`}
+      </text>
+    </box>
+  );
+}

package/src/activity-rail.ts

@@ -0,0 +1,135 @@
+import type { BoxRenderable, Renderable } from "@opentui/core";
+import type { Plugin } from "@opencode/plugin/tui";
+
+// Compatibility boundary: OpenCode 2.0.7 has no public left-tab-rail slot.
+export function activityRail(
+  ctx: Plugin.Context,
+  core: Pick<
+    typeof import("@opentui/core"),
+    "BoxRenderable" | "ScrollBoxRenderable"
+  >,
+  mount: (rail: BoxRenderable) => () => void,
+) {
+  const { BoxRenderable, ScrollBoxRenderable } = core;
+  let owned:
+    | {
+        rail: BoxRenderable;
+        content: BoxRenderable;
+        restore: Map<Renderable, boolean>;
+        cleanup: () => void;
+      }
+    | undefined;
+  let enabled = true;
+  let dirty = true;
+  let geometry = "";
+  const detach = () => {
+    if (!owned) return;
+    owned.cleanup();
+    if (!owned.content.isDestroyed) owned.content.destroyRecursively();
+    for (const [child, visible] of owned.restore)
+      if (!child.isDestroyed) child.visible = visible;
+    owned = undefined;
+  };
+  const find = () => {
+    const matches: BoxRenderable[] = [];
+    const queue: { node: Renderable; depth: number }[] = [
+      { node: ctx.renderer.root, depth: 0 },
+    ];
+    let count = 0;
+    while (queue.length && count++ < 128) {
+      const entry = queue.shift();
+      if (!entry) break;
+      const children = entry.node.getChildren();
+      for (const child of children) {
+        if (
+          child instanceof BoxRenderable &&
+          child.visible &&
+          child.screenX === 0 &&
+          child.screenY === 0 &&
+          child.width >= 24 &&
+          child.width <= 60 &&
+          child.height === ctx.renderer.height &&
+          child
+            .getChildren()
+            .some((node) => node instanceof ScrollBoxRenderable) &&
+          children.filter(
+            (sibling) =>
+              sibling !== child &&
+              sibling.screenX === child.width &&
+              sibling.screenY === 0 &&
+              sibling.height === child.height &&
+              sibling.width >= 60,
+          ).length === 1
+        )
+          matches.push(child);
+        if (entry.depth < 4)
+          queue.push({ node: child, depth: entry.depth + 1 });
+      }
+    }
+    return queue.length === 0 && matches.length === 1 ? matches[0] : undefined;
+  };
+  const frame = () => {
+    if (owned?.rail.isDestroyed || owned?.content.isDestroyed) {
+      detach();
+      dirty = true;
+    }
+    const current = `${ctx.renderer.width}:${ctx.renderer.height}:${owned?.rail.width}:${owned?.rail.height}`;
+    if (current !== geometry) {
+      geometry = current;
+      dirty = true;
+    }
+    if (!dirty) return;
+    dirty = false;
+    const rail = enabled && ctx.ui.tabs.enabled() ? find() : undefined;
+    if (owned?.rail !== rail) detach();
+    if (!rail) return;
+    if (!owned) {
+      const content = new BoxRenderable(ctx.renderer, {
+        id: "op-threads-activity",
+        position: "absolute",
+        left: 0,
+        top: 0,
+        width: "100%",
+        height: "100%",
+        paddingLeft: 1,
+        paddingRight: 2,
+        flexDirection: "column",
+        onMouseDown: (event) => event.stopPropagation(),
+        onMouseUp: (event) => event.stopPropagation(),
+      });
+      rail.add(content);
+      owned = { rail, content, restore: new Map(), cleanup: mount(content) };
+    }
+    for (const child of rail.getChildren()) {
+      if (child === owned.content) continue;
+      if (!owned.restore.has(child)) owned.restore.set(child, child.visible);
+      child.visible = false;
+    }
+    for (const child of owned.restore.keys())
+      if (child.isDestroyed) owned.restore.delete(child);
+  };
+  const invalidate = () => {
+    dirty = true;
+    ctx.renderer.requestRender();
+  };
+  const beforeFrame = async () => frame();
+  ctx.renderer.setFrameCallback(beforeFrame);
+  ctx.renderer.on("resize", invalidate);
+  invalidate();
+  return {
+    invalidate,
+    enabled: () => enabled,
+    mounted: () =>
+      Boolean(owned && !owned.rail.isDestroyed && !owned.content.isDestroyed),
+    toggle(value = !enabled) {
+      enabled = value;
+      if (!enabled) detach();
+      invalidate();
+    },
+    dispose() {
+      ctx.renderer.removeFrameCallback(beforeFrame);
+      ctx.renderer.off("resize", invalidate);
+      detach();
+    },
+  };
+}

package/src/activity-theme.ts

@@ -0,0 +1,49 @@
+import type { ResolvedTheme } from "@opencode/theme/tui";
+
+type Color = ResolvedTheme["text"]["base"];
+type ColorToken =
+  | { readonly base: Color | undefined }
+  | { readonly default: Color | undefined };
+type MutedToken =
+  | { readonly muted: Color | undefined }
+  | { readonly subdued: Color | undefined };
+
+export function themeColor(token: ColorToken, fallback: Color) {
+  return ("base" in token ? token.base : token.default) ?? fallback;
+}
+
+export function themeMuted(token: MutedToken, fallback: Color) {
+  return ("muted" in token ? token.muted : token.subdued) ?? fallback;
+}
+
+function luminance(color: Color) {
+  const linear = (value: number) =>
+    value <= 0.04045 ? value / 12.92 : ((value + 0.055) / 1.055) ** 2.4;
+  return (
+    0.2126 * linear(color.r) +
+    0.7152 * linear(color.g) +
+    0.0722 * linear(color.b)
+  );
+}
+
+export function themeHue(
+  hue: Partial<ResolvedTheme["hue"]["accent"]> | undefined,
+  foreground: Color,
+  background: Color,
+) {
+  const target = luminance(foreground);
+  let selected = foreground;
+  let distance = Infinity;
+  for (const color of Object.values(hue ?? {})) {
+    if (!color) continue;
+    const delta = Math.abs(luminance(color) - target);
+    if (delta >= distance) continue;
+    selected = color;
+    distance = delta;
+  }
+  const light = luminance(selected);
+  const base = luminance(background);
+  const contrast =
+    (Math.max(light, base) + 0.05) / (Math.min(light, base) + 0.05);
+  return contrast >= 4.5 ? selected : foreground;
+}