indusagi-coding-agent 0.2.8 → 0.2.9

package/src/conductor/signal-hub/translate.test.ts

@@ -0,0 +1,81 @@
+import { describe, expect, it } from "vitest";
+import { translateAgentEvent } from "./translate.js";
+
+type InputEvent = Parameters<typeof translateAgentEvent>[0];
+
+describe("translateAgentEvent tool signals", () => {
+  it("includes tool arguments in tool_start", () => {
+    const event: InputEvent = {
+      type: "tool_execution_start",
+      toolCallId: "call-1",
+      toolName: "read",
+      args: { path: "README.md" },
+    };
+
+    expect(translateAgentEvent(event)).toEqual([{
+      kind: "tool_start",
+      id: "call-1",
+      name: "read",
+      args: { path: "README.md" },
+    }]);
+  });
+
+  it("includes tool results and error status in tool_end", () => {
+    const event: InputEvent = {
+      type: "tool_execution_end",
+      toolCallId: "call-2",
+      toolName: "write",
+      result: { content: "permission denied" },
+      isError: true,
+    };
+
+    expect(translateAgentEvent(event)).toEqual([{
+      kind: "tool_end",
+      id: "call-2",
+      ok: false,
+      result: { content: "permission denied" },
+      isError: true,
+    }]);
+  });
+});
+
+describe("translateAgentEvent preserved signals", () => {
+  it("preserves prompt extraction", () => {
+    const event = {
+      type: "message_end",
+      message: {
+        role: "user",
+        content: [{ type: "text", text: "hello " }, { type: "text", text: "world" }],
+        timestamp: 1,
+      },
+    } as unknown as InputEvent;
+
+    expect(translateAgentEvent(event)).toEqual([{ kind: "prompt", text: "hello world" }]);
+  });
+
+  it("preserves text and thinking deltas", () => {
+    const message = { role: "assistant", content: [], timestamp: 1 };
+
+    expect(translateAgentEvent({
+      type: "message_update",
+      message,
+      assistantMessageEvent: { type: "text_delta", delta: "answer" },
+    } as unknown as InputEvent)).toEqual([{ kind: "text", delta: "answer" }]);
+    expect(translateAgentEvent({
+      type: "message_update",
+      message,
+      assistantMessageEvent: { type: "thinking_delta", delta: "reason" },
+    } as unknown as InputEvent)).toEqual([{ kind: "thinking", delta: "reason" }]);
+  });
+
+  it("preserves turn_end usage", () => {
+    const usage = { input: 1, output: 2, cacheRead: 3, cacheWrite: 4, totalTokens: 10, cost: { total: 0.5 } };
+    const event = {
+      type: "turn_end",
+      message: { role: "assistant", content: [], usage, timestamp: 1 },
+      toolResults: [],
+    } as unknown as InputEvent;
+
+    expect(translateAgentEvent(event)).toEqual([{ kind: "turn_end", usage }]);
+  });
+});

package/src/conductor/signal-hub/translate.ts

@@ -0,0 +1,74 @@
+import type { AgentEvent, AgentEventType, ExtractAgentEvent } from "indusagi/agent";
+import { createZeroUsage } from "indusagi/ai";
+import { conductorFault } from "../contract.js";
+import type { SessionSignal } from "../contract.js";
+
+type TranslatorRule<TType extends AgentEventType> = (event: ExtractAgentEvent<TType>) => SessionSignal[];
+type TranslatorTable = { [K in AgentEventType]: TranslatorRule<K> };
+
+const none = (): SessionSignal[] => [];
+
+function usageOf(message: unknown) {
+  if (typeof message === "object" && message !== null && "usage" in message && message.usage != null) return message.usage;
+  return createZeroUsage();
+}
+
+function faultMessageOf(error: unknown): string {
+  if (typeof error === "object" && error !== null && "errorMessage" in error && typeof error.errorMessage === "string") {
+    return error.errorMessage;
+  }
+  return "model stream error";
+}
+
+function translateStreamEvent(sub: any): SessionSignal[] {
+  switch (sub.type) {
+    case "text_delta": return [{ kind: "text", delta: sub.delta }];
+    case "thinking_delta": return [{ kind: "thinking", delta: sub.delta }];
+    case "error": return [{ kind: "fault", fault: conductorFault("model", faultMessageOf(sub.error), sub.error) }];
+    default: return [];
+  }
+}
+
+function promptTextOf(content: unknown): string {
+  if (typeof content === "string") return content;
+  if (Array.isArray(content)) {
+    return content.map((block) => typeof block === "object" && block !== null && "text" in block && typeof block.text === "string" ? block.text : "").join("");
+  }
+  return "";
+}
+
+export const TRANSLATOR_TABLE: TranslatorTable = {
+  agent_start: none,
+  agent_end: none,
+  turn_start: none,
+  message_start: none,
+  message_end: (event) => {
+    const message = event.message;
+    if (message?.role === "user") return [{ kind: "prompt", text: promptTextOf(message.content) }];
+    if (message?.role === "assistant" && (message.stopReason === "error" || typeof message.errorMessage === "string")) {
+      return [{ kind: "fault", fault: conductorFault("model", message.errorMessage ?? "the model call failed") }];
+    }
+    return [];
+  },
+  turn_end: (event) => [{ kind: "turn_end", usage: usageOf(event.message) }],
+  message_update: (event) => translateStreamEvent(event.assistantMessageEvent),
+  tool_execution_start: (event) => [{ kind: "tool_start", id: event.toolCallId, name: event.toolName, args: event.args } as SessionSignal],
+  tool_execution_update: (event) => [{
+    kind: "tool_update",
+    id: event.toolCallId,
+    name: event.toolName,
+    details: event.partialResult?.details,
+  }],
+  tool_execution_end: (event) => [{
+    kind: "tool_end",
+    id: event.toolCallId,
+    ok: !event.isError,
+    result: event.result,
+    isError: event.isError,
+  } as SessionSignal],
+};
+
+export function translateAgentEvent(event: AgentEvent): SessionSignal[] {
+  const rule = TRANSLATOR_TABLE[event.type] as (event: AgentEvent) => SessionSignal[];
+  return rule(event);
+}

package/src/conductor/skill-parse/index.ts

@@ -0,0 +1,2 @@
+export { parseSkillInvocation } from "./parse.js";
+export type { SkillInvocation } from "./parse.js";

package/src/conductor/skill-parse/parse.ts

@@ -0,0 +1,108 @@
+export interface SkillInvocation {
+  readonly name: string;
+  readonly args: Record<string, string>;
+  readonly body: string;
+}
+
+const SKILL_TAG = "skill";
+const NAME_ATTR = "name";
+
+function isSpace(ch: string | undefined): boolean {
+  return ch === " " || ch === "\t" || ch === "\n" || ch === "\r" || ch === "\f" || ch === "\v";
+}
+function isKeyStart(ch: string | undefined): boolean {
+  return ch !== undefined && ((ch >= "a" && ch <= "z") || (ch >= "A" && ch <= "Z") || ch === "_");
+}
+function isKeyChar(ch: string | undefined): boolean {
+  return isKeyStart(ch) || (ch !== undefined && ch >= "0" && ch <= "9") || ch === "-" || ch === ":" || ch === ".";
+}
+function skipSpace(text: string, index: number): number {
+  while (index < text.length && isSpace(text[index])) index++;
+  return index;
+}
+function decodeEntities(raw: string): string {
+  if (!raw.includes("&")) return raw;
+  return raw.replace(/&(#39|#x27|#34|#x22|amp|lt|gt|quot|apos);/gi, (match, code: string) => {
+    switch (code.toLowerCase()) {
+      case "amp": return "&";
+      case "lt": return "<";
+      case "gt": return ">";
+      case "quot": case "#34": case "#x22": return '"';
+      case "apos": case "#39": case "#x27": return "'";
+      default: return match;
+    }
+  });
+}
+function scanAttribute(text: string, index: number): { key: string; value: string; next: number } | null {
+  let cursor = index;
+  if (!isKeyStart(text[cursor])) return null;
+  cursor++;
+  while (cursor < text.length && isKeyChar(text[cursor])) cursor++;
+  const key = text.slice(index, cursor).toLowerCase();
+  const afterKey = skipSpace(text, cursor);
+  if (text[afterKey] !== "=") return { key, value: "", next: cursor };
+  cursor = skipSpace(text, afterKey + 1);
+  const quote = text[cursor];
+  if (quote === '"' || quote === "'") {
+    const start = cursor + 1;
+    let end = start;
+    while (end < text.length && text[end] !== quote) end++;
+    if (end >= text.length) return { key, value: decodeEntities(text.slice(start)), next: text.length };
+    return { key, value: decodeEntities(text.slice(start, end)), next: end + 1 };
+  }
+  const start = cursor;
+  while (cursor < text.length && !isSpace(text[cursor]) && text[cursor] !== ">" && text[cursor] !== "/") cursor++;
+  return { key, value: decodeEntities(text.slice(start, cursor)), next: cursor };
+}
+function trimBodyEdges(body: string): string {
+  let result = body;
+  if (result.startsWith("\r\n")) result = result.slice(2);
+  else if (result.startsWith("\n") || result.startsWith("\r")) result = result.slice(1);
+  if (result.endsWith("\r\n")) result = result.slice(0, -2);
+  else if (result.endsWith("\n") || result.endsWith("\r")) result = result.slice(0, -1);
+  return result;
+}
+function findCloseTag(text: string, index: number): number | null {
+  let cursor = index;
+  while (cursor < text.length) {
+    const left = text.indexOf("<", cursor);
+    if (left === -1) return null;
+    let scan = left + 1;
+    if (text[scan] !== "/") { cursor = left + 1; continue; }
+    scan = skipSpace(text, scan + 1);
+    const start = scan;
+    while (scan < text.length && isKeyChar(text[scan])) scan++;
+    if (text.slice(start, scan).toLowerCase() !== SKILL_TAG) { cursor = left + 1; continue; }
+    scan = skipSpace(text, scan);
+    if (text[scan] === ">") return left;
+    cursor = left + 1;
+  }
+  return null;
+}
+
+export function parseSkillInvocation(text: string): SkillInvocation | null {
+  let index = skipSpace(text, 0);
+  if (text[index] !== "<") return null;
+  index++;
+  const tagStart = index;
+  while (index < text.length && isKeyChar(text[index])) index++;
+  if (text.slice(tagStart, index).toLowerCase() !== SKILL_TAG) return null;
+  const afterTag = text[index];
+  if (afterTag !== undefined && !isSpace(afterTag) && afterTag !== ">" && afterTag !== "/") return null;
+  const args: Record<string, string> = {};
+  for (;;) {
+    index = skipSpace(text, index);
+    const ch = text[index];
+    if (ch === undefined || ch === "/") return null;
+    if (ch === ">") { index++; break; }
+    const scan = scanAttribute(text, index);
+    if (!scan) return null;
+    if (!(scan.key in args)) args[scan.key] = scan.value;
+    index = scan.next;
+  }
+  const name = args[NAME_ATTR];
+  if (!name) return null;
+  const close = findCloseTag(text, index);
+  if (close === null) return null;
+  return { name, args, body: trimBodyEdges(decodeEntities(text.slice(index, close))) };
+}

package/src/conductor/transcript-store/index.ts

@@ -0,0 +1,22 @@
+export {
+  TranscriptStore,
+  memoryBackend,
+  fsBackend,
+  replay,
+  type TranscriptBackend,
+  type TranscriptState,
+  type TranscriptClock,
+  type TranscriptStoreOptions,
+} from "./store.js";
+export {
+  roleForMessage,
+  encodeEntry,
+  encodeHead,
+  parseSessionText,
+  branchToMessages,
+  branchToLlmMessages,
+  importLegacyFile,
+  importLegacyText,
+  resolveLegacyMessages,
+  type ParsedSessionFile,
+} from "./serialize.js";

package/src/conductor/transcript-store/serialize.ts

@@ -0,0 +1,116 @@
+import { buildSessionContext, convertToLlm, loadEntriesFromFile, parseSessionEntries } from "indusagi/agent";
+import type { AgentMessage } from "indusagi/agent";
+import type { Message } from "indusagi/ai";
+import { TRANSCRIPT_SCHEMA } from "../contract.js";
+import type { SessionHead, TranscriptEntry, TranscriptRole } from "../contract.js";
+
+export interface ParsedSessionFile {
+  readonly head: SessionHead | null;
+  readonly entries: TranscriptEntry[];
+}
+
+export function roleForMessage(message: AgentMessage): TranscriptRole {
+  switch (message.role) {
+    case "user": return "user";
+    case "assistant": return "assistant";
+    case "toolResult": return "tool";
+    case "compactionSummary":
+    case "branchSummary": return "condense";
+    default: return "note";
+  }
+}
+
+export function encodeEntry(entry: TranscriptEntry): string {
+  return JSON.stringify({
+    schema: TRANSCRIPT_SCHEMA,
+    kind: "entry",
+    id: entry.id,
+    prev: entry.parent,
+    role: entry.role,
+    message: entry.content,
+    at: entry.createdAt,
+    ...(entry.meta !== undefined ? { meta: entry.meta } : {}),
+  });
+}
+
+export function encodeHead(head: SessionHead): string {
+  return JSON.stringify({
+    schema: TRANSCRIPT_SCHEMA,
+    kind: "head",
+    sessionId: head.sessionId,
+    leaf: head.leaf,
+    ...(head.usage !== undefined ? { usage: head.usage } : {}),
+  });
+}
+
+function isFileLine(value: unknown): value is any {
+  return typeof value === "object" && value !== null && (value as any).schema === TRANSCRIPT_SCHEMA
+    && ((value as any).kind === "head" || (value as any).kind === "entry");
+}
+
+export function parseSessionText(sessionId: string, text: string): ParsedSessionFile {
+  const entries: TranscriptEntry[] = [];
+  let leaf: string | null | undefined;
+  let usage: SessionHead["usage"];
+  for (const raw of text.split("\n")) {
+    const trimmed = raw.trim();
+    if (!trimmed) continue;
+    let parsed: unknown;
+    try { parsed = JSON.parse(trimmed); } catch { continue; }
+    if (!isFileLine(parsed)) continue;
+    if (parsed.kind === "head") {
+      leaf = parsed.leaf;
+      usage = parsed.usage;
+    } else {
+      entries.push({
+        id: parsed.id,
+        parent: parsed.prev,
+        role: parsed.role,
+        content: parsed.message,
+        createdAt: parsed.at,
+        ...(parsed.meta !== undefined ? { meta: parsed.meta } : {}),
+      });
+    }
+  }
+  return {
+    head: leaf === undefined ? null : { sessionId, leaf, ...(usage !== undefined ? { usage } : {}) },
+    entries,
+  };
+}
+
+export function branchToMessages(branch: readonly TranscriptEntry[]): AgentMessage[] {
+  return branch.map((entry) => entry.content);
+}
+
+export function branchToLlmMessages(branch: readonly TranscriptEntry[]): Message[] {
+  return convertToLlm(branchToMessages(branch)) as Message[];
+}
+
+function legacyEntriesToTranscript(entries: any[]): TranscriptEntry[] {
+  const messages = buildSessionContext(entries).messages as AgentMessage[];
+  let parent: string | null = null;
+  return messages.map((content, index) => {
+    const id = `legacy_${index.toString(36)}`;
+    const entry: TranscriptEntry = {
+      id,
+      parent,
+      role: roleForMessage(content),
+      content,
+      createdAt: new Date(0).toISOString(),
+    };
+    parent = id;
+    return entry;
+  });
+}
+
+export function importLegacyFile(filePath: string): TranscriptEntry[] {
+  return legacyEntriesToTranscript(loadEntriesFromFile(filePath) as any[]);
+}
+
+export function importLegacyText(text: string): TranscriptEntry[] {
+  return legacyEntriesToTranscript(parseSessionEntries(text) as any[]);
+}
+
+export function resolveLegacyMessages(filePath: string): AgentMessage[] {
+  return buildSessionContext(loadEntriesFromFile(filePath) as any[]).messages as AgentMessage[];
+}

package/src/conductor/transcript-store/store.ts

@@ -0,0 +1,205 @@
+import { ulid } from "ulid";
+import type { AgentMessage } from "indusagi/agent";
+import type { Usage } from "indusagi/ai";
+import { TRANSCRIPT_SCHEMA } from "../contract.js";
+import type { SessionHead, TranscriptEntry, TranscriptRole } from "../contract.js";
+import { encodeEntry, encodeHead, parseSessionText, roleForMessage } from "./serialize.js";
+
+export interface TranscriptBackend {
+  locate(sessionId: string): string;
+  read(sessionId: string): Promise<string | null>;
+  append(sessionId: string, line: string): Promise<void>;
+  rewrite(sessionId: string, text: string): Promise<void>;
+}
+
+export interface TranscriptState {
+  readonly nodes: ReadonlyMap<string, TranscriptEntry>;
+  readonly head: SessionHead;
+}
+
+export interface TranscriptClock {
+  readonly id: () => string;
+  readonly now: () => string;
+}
+
+export interface TranscriptStoreOptions {
+  readonly backend?: TranscriptBackend;
+  readonly clock?: TranscriptClock;
+}
+
+export function memoryBackend(): TranscriptBackend {
+  const files = new Map<string, string[]>();
+  return {
+    locate: (sessionId) => `mem:${sessionId}`,
+    read: async (sessionId) => {
+      const lines = files.get(sessionId);
+      return lines ? lines.join("\n") : null;
+    },
+    append: async (sessionId, line) => {
+      const lines = files.get(sessionId) ?? [];
+      lines.push(line);
+      files.set(sessionId, lines);
+    },
+    rewrite: async (sessionId, text) => {
+      files.set(sessionId, text.length === 0 ? [] : text.split("\n"));
+    },
+  };
+}
+
+export function fsBackend(dir: string): TranscriptBackend {
+  const fileOf = async (sessionId: string) => {
+    const path = await import("node:path");
+    return path.join(dir, `${sessionId}.ndjson`);
+  };
+  return {
+    locate: (sessionId) => `${dir}/${sessionId}.ndjson`,
+    read: async (sessionId) => {
+      const fs = await import("node:fs/promises");
+      try { return await fs.readFile(await fileOf(sessionId), "utf8"); } catch { return null; }
+    },
+    append: async (sessionId, line) => {
+      const fs = await import("node:fs/promises");
+      await fs.mkdir(dir, { recursive: true });
+      await fs.appendFile(await fileOf(sessionId), `${line}\n`, "utf8");
+    },
+    rewrite: async (sessionId, text) => {
+      const fs = await import("node:fs/promises");
+      await fs.mkdir(dir, { recursive: true });
+      await fs.writeFile(await fileOf(sessionId), text.length === 0 ? "" : `${text}\n`, "utf8");
+    },
+  };
+}
+
+export function replay(sessionId: string, entries: readonly TranscriptEntry[], leaf: string | null): TranscriptState {
+  const nodes = new Map<string, TranscriptEntry>();
+  for (const entry of entries) nodes.set(entry.id, entry);
+  return { nodes, head: { sessionId, leaf } };
+}
+
+function deepestLeaf(entries: readonly TranscriptEntry[]): string | null {
+  if (entries.length === 0) return null;
+  const byId = new Map(entries.map((entry) => [entry.id, entry]));
+  const depthOf = (id: string) => {
+    let depth = 0;
+    let cursor: string | null = id;
+    const seen = new Set<string>();
+    while (cursor !== null && !seen.has(cursor)) {
+      seen.add(cursor);
+      const node = byId.get(cursor);
+      if (!node) break;
+      depth++;
+      cursor = node.parent;
+    }
+    return depth;
+  };
+  let best = entries[0];
+  let bestDepth = depthOf(best.id);
+  for (const entry of entries) {
+    const depth = depthOf(entry.id);
+    if (depth > bestDepth || (depth === bestDepth && entry.id > best.id)) {
+      best = entry;
+      bestDepth = depth;
+    }
+  }
+  return best.id;
+}
+
+const liveClock: TranscriptClock = { id: () => ulid(), now: () => new Date().toISOString() };
+
+export class TranscriptStore {
+  #state: TranscriptState;
+  readonly #backend: TranscriptBackend;
+  readonly #clock: TranscriptClock;
+
+  constructor(sessionId: string, options: TranscriptStoreOptions = {}) {
+    this.#backend = options.backend ?? memoryBackend();
+    this.#clock = options.clock ?? liveClock;
+    this.#state = replay(sessionId, [], null);
+  }
+
+  get sessionId(): string { return this.#state.head.sessionId; }
+  get head(): SessionHead { return this.#state.head; }
+  get usage(): Usage | undefined { return this.#state.head.usage; }
+  get size(): number { return this.#state.nodes.size; }
+  locate(sessionId = this.sessionId): string { return this.#backend.locate(sessionId); }
+  get(id: string): TranscriptEntry | undefined { return this.#state.nodes.get(id); }
+
+  async append(content: AgentMessage, role?: TranscriptRole, meta?: Readonly<Record<string, unknown>>): Promise<TranscriptEntry> {
+    const entry: TranscriptEntry = {
+      id: this.#clock.id(),
+      parent: this.#state.head.leaf,
+      role: role ?? roleForMessage(content),
+      content,
+      createdAt: this.#clock.now(),
+      ...(meta !== undefined ? { meta } : {}),
+    };
+    await this.#backend.append(this.sessionId, encodeEntry(entry));
+    this.#commit(entry);
+    return entry;
+  }
+
+  async persistUsage(usage: Usage): Promise<void> {
+    this.#state = { nodes: this.#state.nodes, head: { ...this.#state.head, usage } };
+    await this.#flush();
+  }
+
+  async branchAt(id: string): Promise<void> {
+    if (!this.#state.nodes.has(id)) throw new Error(`TranscriptStore.branchAt: unknown node "${id}"`);
+    this.#state = { nodes: this.#state.nodes, head: { sessionId: this.sessionId, leaf: id } };
+    await this.#flush();
+  }
+
+  async reset(): Promise<void> {
+    this.#state = { nodes: this.#state.nodes, head: { sessionId: this.sessionId, leaf: null } };
+    await this.#flush();
+  }
+
+  startNewSession(sessionId: string): void { this.#state = replay(sessionId, [], null); }
+
+  pathTo(from?: string): TranscriptEntry[] {
+    const chain: TranscriptEntry[] = [];
+    let cursor = from ?? this.#state.head.leaf;
+    const seen = new Set<string>();
+    while (cursor !== null) {
+      if (seen.has(cursor)) break;
+      seen.add(cursor);
+      const node = this.#state.nodes.get(cursor);
+      if (!node) break;
+      chain.push(node);
+      cursor = node.parent;
+    }
+    return chain.reverse();
+  }
+
+  messages(from?: string): AgentMessage[] { return this.pathTo(from).map((entry) => entry.content); }
+
+  async load(sessionId = this.sessionId): Promise<boolean> {
+    const text = await this.#backend.read(sessionId);
+    if (text === null) return false;
+    const parsed = parseSessionText(sessionId, text);
+    const leaf = parsed.head?.leaf ?? deepestLeaf(parsed.entries);
+    const base = replay(sessionId, parsed.entries, leaf);
+    this.#state = parsed.head?.usage === undefined ? base : { nodes: base.nodes, head: { ...base.head, usage: parsed.head.usage } };
+    return true;
+  }
+
+  static async open(sessionId: string, options: TranscriptStoreOptions = {}): Promise<TranscriptStore | null> {
+    const store = new TranscriptStore(sessionId, options);
+    return await store.load(sessionId) ? store : null;
+  }
+
+  state(): TranscriptState { return this.#state; }
+
+  #commit(entry: TranscriptEntry): void {
+    const nodes = new Map(this.#state.nodes);
+    nodes.set(entry.id, entry);
+    this.#state = { nodes, head: { sessionId: this.sessionId, leaf: entry.id } };
+  }
+
+  async #flush(): Promise<void> {
+    const lines = [encodeHead(this.#state.head), ...[...this.#state.nodes.values()].map(encodeEntry)];
+    await this.#backend.rewrite(this.sessionId, lines.join("\n"));
+  }
+}
+
+export { TRANSCRIPT_SCHEMA };

package/src/console/auth-status.ts

@@ -0,0 +1,56 @@
+/**
+ * Shared "does the user have a usable credential for this provider" probe.
+ *
+ * Used anywhere the console needs to know which providers are actually
+ * callable — the `/model` picker (only list authenticated providers) and the
+ * banner's Session panel (don't display an unauthenticated model as if it were
+ * ready to use) both need the exact same answer, so it lives here once.
+ */
+import { useEffect, useState } from "indusagi/react-host";
+import { hasValidServerToken } from "../boot/server-token.js";
+import { serverTierProviders } from "../boot/runners/server-mode.js";
+import type { OverlayServices } from "./contract.js";
+
+/**
+ * Load the set of provider ids the user has USABLE credentials for, live.
+ *
+ * Two independent sources count: (1) any saved account in the local vault for a
+ * provider `listLoginProviders()` names, and (2) a valid server session token,
+ * which makes every gateway-eligible provider usable even though the server
+ * tier never writes into the vault. Returns `null` until the probe settles.
+ */
+export function useAuthenticatedProviders(services: OverlayServices | undefined, refreshKey?: unknown): Set<string> | null {
+  const [authed, setAuthed] = useState<Set<string> | null>(null);
+  useEffect(() => {
+    if (!services) return;
+    let live = true;
+    void (async () => {
+      const found = new Set<string>();
+      try {
+        for (const provider of services.listLoginProviders()) {
+          try {
+            if ((await services.vault.listAccounts(provider.id)).length > 0) {
+              found.add(provider.id);
+            }
+          } catch {
+            // ignore
+          }
+        }
+      } catch {
+        // ignore
+      }
+      try {
+        if (await hasValidServerToken()) {
+          for (const provider of serverTierProviders()) found.add(provider);
+        }
+      } catch {
+        // ignore
+      }
+      if (live) setAuthed(found);
+    })();
+    return () => {
+      live = false;
+    };
+  }, [refreshKey]);
+  return authed;
+}