@hienlh/ppm 0.19.2 → 0.19.3

package/src/services/provider-usage/usage-registry.ts

@@ -0,0 +1,157 @@
+import type { UsageInfo } from "../../types/chat.ts";
+import {
+  AMBIENT_ACCOUNT_KEY,
+  FETCH_TIMEOUT_MS,
+  type ProviderUsageSource,
+} from "./usage-source.ts";
+import {
+  getCachedUsageEntry,
+  isRecentlyFailed,
+  setCachedFailure,
+  setCachedUsage,
+  invalidateCachedUsage,
+} from "./usage-memory-cache.ts";
+import { readStoredUsage, writeStoredUsage } from "./usage-snapshot-store.ts";
+
+/**
+ * Registry of provider usage sources, and the read/refresh path over them.
+ *
+ * The rule the whole layer exists to enforce: **reads never wait on a provider.**
+ * `getUsage` is synchronous and answers from memory, falling back to the stored
+ * snapshot. Anything that talks to a provider happens on the background sweep or
+ * behind an explicit refresh, both of which are bounded by a timeout.
+ */
+
+const sources = new Map<string, ProviderUsageSource>();
+
+export function registerUsageSource(source: ProviderUsageSource): void {
+  sources.set(source.providerId, source);
+}
+
+export function getUsageSource(providerId: string): ProviderUsageSource | undefined {
+  return sources.get(providerId);
+}
+
+export function listUsageSources(): ProviderUsageSource[] {
+  return [...sources.values()];
+}
+
+/** Test seam: drop every registered source. */
+export function _clearUsageSources(): void {
+  sources.clear();
+}
+
+/**
+ * Latest known usage for one account, without ever touching the provider.
+ *
+ * Memory first, then the stored snapshot — which is what makes a percentage
+ * appear immediately after a restart, before the first sweep lands. Returns an
+ * empty object when nothing has ever been recorded; the caller cannot tell that
+ * apart from "no limits reported", and does not need to.
+ */
+export function getUsage(providerId: string, accountId = AMBIENT_ACCOUNT_KEY): UsageInfo {
+  const cached = getCachedUsageEntry(providerId, accountId);
+  if (cached) return cached;
+  const stored = readStoredUsage(providerId, accountId);
+  if (stored) {
+    // Promote into memory so the next read skips the query, but keep the
+    // provider's own freshness clock: this value is as old as it ever was.
+    setCachedUsage(providerId, accountId, stored);
+    return stored;
+  }
+  return {};
+}
+
+/** Reject if `promise` has not settled within `ms`, naming what timed out. */
+function withTimeout<T>(promise: Promise<T>, ms: number, what: string): Promise<T> {
+  return new Promise<T>((resolve, reject) => {
+    const timer = setTimeout(() => reject(new Error(`${what} timed out after ${ms}ms`)), ms);
+    promise.then(
+      (v) => { clearTimeout(timer); resolve(v); },
+      (e) => { clearTimeout(timer); reject(e); },
+    );
+  });
+}
+
+/**
+ * Concurrent refreshes of the same account share one in-flight fetch.
+ *
+ * Each attempt carries a token so its cleanup can tell "I am still the current
+ * attempt" from "I was abandoned and something newer took my place".
+ */
+const inflight = new Map<string, { token: object; promise: Promise<UsageInfo> }>();
+
+/**
+ * Fetch one account live, then cache and store it.
+ *
+ * Failures are swallowed into the last known value rather than propagated: the
+ * callers are a background sweep and a toolbar refresh, and neither has anything
+ * useful to do with the error beyond showing what it already had. The failure is
+ * still remembered so it does not turn into a retry per request.
+ */
+export async function refreshUsage(
+  providerId: string,
+  accountId = AMBIENT_ACCOUNT_KEY,
+): Promise<UsageInfo> {
+  const source = sources.get(providerId);
+  if (!source) return {};
+
+  const key = `${providerId}\0${accountId}`;
+  const existing = inflight.get(key);
+  if (existing) return existing.promise;
+
+  // Identity for this attempt. Comparing tokens rather than the promise avoids
+  // the closure having to reference the very promise it is producing.
+  const token = {};
+  const run = (async () => {
+    try {
+      const usage = await withTimeout(
+        source.fetch(accountId),
+        source.fetchTimeoutMs ?? FETCH_TIMEOUT_MS,
+        `${providerId} usage fetch`,
+      );
+      setCachedUsage(providerId, accountId, usage);
+      writeStoredUsage(providerId, accountId, usage);
+      return usage;
+    } catch (e) {
+      setCachedFailure(providerId, accountId);
+      console.error(`[usage] ${providerId}/${accountId || "ambient"}:`, (e as Error).message);
+      return readStoredUsage(providerId, accountId) ?? {};
+    } finally {
+      // Only clear if this is still the current attempt. An abandoned fetch
+      // that finishes late must not evict the entry a newer one just installed,
+      // or that newer caller would be silently un-deduped.
+      if (inflight.get(key)?.token === token) inflight.delete(key);
+    }
+  })();
+
+  inflight.set(key, { token, promise: run });
+  return run;
+}
+
+/** Test seam: forget every in-flight fetch so the next call starts a fresh one. */
+export function _clearInflightUsage(): void {
+  inflight.clear();
+}
+
+/**
+ * Read, fetching only if nothing usable is known yet.
+ *
+ * Used by the request path so a cold start still produces a number, while a
+ * remembered failure short-circuits to the stored value instead of re-attempting
+ * a fetch on every request.
+ */
+export async function getOrFetchUsage(
+  providerId: string,
+  accountId = AMBIENT_ACCOUNT_KEY,
+): Promise<UsageInfo> {
+  const known = getUsage(providerId, accountId);
+  if (Object.keys(known).length > 0) return known;
+  if (isRecentlyFailed(providerId, accountId)) return known;
+  return refreshUsage(providerId, accountId);
+}
+
+/** Force the next read of this provider (or one account) to go back to the source. */
+export function invalidateUsage(providerId: string, accountId?: string): void {
+  invalidateCachedUsage(providerId, accountId);
+}

package/src/services/provider-usage/usage-scheduler.ts

@@ -0,0 +1,117 @@
+import {
+  ACCOUNT_STAGGER_MS,
+  AMBIENT_ACCOUNT_KEY,
+  DEFAULT_POLL_INTERVAL_MS,
+  type ProviderUsageSource,
+} from "./usage-source.ts";
+import { listUsageSources, refreshUsage } from "./usage-registry.ts";
+
+/**
+ * The one background loop that keeps every provider's quota warm.
+ *
+ * Sweeping in the background is what makes reads instant: by the time the
+ * toolbar asks, the value is already in memory. Both providers run on the same
+ * cadence and through the same code, so a new provider gets this by registering
+ * a source — there is no second timer to write.
+ *
+ * Survives `bun --hot` reloads through globalThis: module state resets on
+ * reload, so a module-level timer would leak a new interval per reload while
+ * the old one kept firing.
+ */
+
+const HOT_KEY = "__PPM_PROVIDER_USAGE_POLL__" as const;
+
+interface HotState {
+  timers: Map<string, ReturnType<typeof setTimeout>>;
+  inflight: Map<string, Promise<void>>;
+}
+
+const hot: HotState = ((globalThis as Record<string, unknown>)[HOT_KEY] ??= {
+  timers: new Map(),
+  inflight: new Map(),
+}) as HotState;
+
+/**
+ * One pass over a source's accounts.
+ *
+ * Accounts are walked in series with a gap between them: a sweep is maintenance,
+ * not something worth spending a burst of subprocesses or API calls on. Each
+ * account is independent — `refreshUsage` never rejects, so a failing account
+ * does not cut the sweep short for the ones after it.
+ */
+async function sweepSource(source: ProviderUsageSource): Promise<void> {
+  const accountIds = source.listAccountIds();
+  // No account store configured: the provider reads one ambient login instead.
+  const targets = accountIds.length > 0 ? accountIds : [AMBIENT_ACCOUNT_KEY];
+
+  for (let i = 0; i < targets.length; i++) {
+    const accountId = targets[i]!;
+    try {
+      if (await source.shouldSkip?.(accountId)) continue;
+    } catch {
+      continue; // A source that cannot decide is treated as "skip", not "fetch".
+    }
+    await refreshUsage(source.providerId, accountId);
+    if (i < targets.length - 1) await new Promise((r) => setTimeout(r, ACCOUNT_STAGGER_MS));
+  }
+}
+
+/** Sweep one source now; concurrent callers share the in-flight pass. */
+export function sweepUsageSource(source: ProviderUsageSource): Promise<void> {
+  const existing = hot.inflight.get(source.providerId);
+  if (existing) return existing;
+
+  const pass = sweepSource(source)
+    .catch((e) => console.error(`[usage] sweep ${source.providerId}:`, (e as Error).message))
+    .finally(() => {
+      // Only clear if still the current pass, so a stale finally cannot drop a newer one.
+      if (hot.inflight.get(source.providerId) === pass) hot.inflight.delete(source.providerId);
+    });
+
+  hot.inflight.set(source.providerId, pass);
+  return pass;
+}
+
+/**
+ * Start the background loop for every registered source.
+ *
+ * Each source is swept once immediately — a fresh server should not show blank
+ * percentages for a whole interval — and then rescheduled after each pass
+ * completes rather than on a fixed interval, so a slow sweep cannot overlap the
+ * next one.
+ */
+export function startProviderUsagePolling(): void {
+  stopProviderUsagePolling();
+  for (const source of listUsageSources()) {
+    const interval = source.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS;
+    const scheduleNext = () => {
+      hot.timers.set(source.providerId, setTimeout(async () => {
+        await sweepUsageSource(source);
+        scheduleNext();
+      }, interval));
+    };
+    sweepUsageSource(source).then(scheduleNext, scheduleNext);
+  }
+}
+
+export function stopProviderUsagePolling(): void {
+  for (const timer of hot.timers.values()) clearTimeout(timer);
+  hot.timers.clear();
+}
+
+/**
+ * Abandon any in-flight sweep so the next one starts fresh.
+ *
+ * Needed when a sweep is known to be stuck: without it the hung pass is handed
+ * to every later caller, and a provider that stops answering blocks its own
+ * refresh indefinitely. The guard in {@link sweepUsageSource} means the
+ * abandoned pass cannot evict its replacement when it eventually settles.
+ */
+export function _clearInflightSweeps(): void {
+  hot.inflight.clear();
+}
+
+/** Test seam: true while any source has a scheduled pass. */
+export function _isUsagePollingActive(): boolean {
+  return hot.timers.size > 0;
+}

package/src/services/provider-usage/usage-snapshot-store.ts

@@ -0,0 +1,126 @@
+import type { UsageInfo, LimitBucket } from "../../types/chat.ts";
+import {
+  insertLimitSnapshot,
+  getLatestLimitSnapshot,
+  getLatestSnapshotForAccount,
+  touchSnapshotTimestamp,
+  cleanupOldLimitSnapshots,
+  type LimitSnapshotRow,
+} from "../db.service.ts";
+import { AMBIENT_ACCOUNT_KEY } from "./usage-source.ts";
+
+/**
+ * The durable half of the usage layer: turning a provider's `UsageInfo` into a
+ * snapshot row and back, for any provider.
+ *
+ * Persistence is what lets the toolbar show a number the moment the server comes
+ * back up, before the first background sweep has finished. Without it a restart
+ * blanks every percentage for as long as the first fetch takes.
+ *
+ * A row is only written when something actually moved. Otherwise the newest row
+ * has its timestamp touched, so "last fetched" stays honest without growing a
+ * row per account per sweep forever.
+ */
+
+/** Recompute a bucket's countdown against the current clock. */
+function toBucket(util: number, resetsAt: string, windowHours: number): LimitBucket {
+  const diff = resetsAt ? new Date(resetsAt).getTime() - Date.now() : 0;
+  const totalMins = diff > 0 ? Math.ceil(diff / 60_000) : 0;
+  return {
+    utilization: util,
+    resetsAt,
+    resetsInMinutes: windowHours <= 5 ? totalMins : null,
+    resetsInHours: windowHours > 5 ? Math.round((totalMins / 60) * 100) / 100 : null,
+    windowHours,
+  };
+}
+
+/** Snapshot row → UsageInfo, with the flat mirror fields the chat toolbar reads. */
+export function snapshotToUsage(row: LimitSnapshotRow): UsageInfo & { lastFetchedAt?: string } {
+  // SQLite's datetime('now') is UTC but carries no Z, which JS would read as local time.
+  const iso = row.recorded_at.endsWith("Z")
+    ? row.recorded_at
+    : row.recorded_at.replace(" ", "T") + "Z";
+  const usage: UsageInfo & { lastFetchedAt?: string } = { lastFetchedAt: iso };
+  if (row.five_hour_util != null) {
+    usage.session = toBucket(row.five_hour_util, row.five_hour_resets_at ?? "", 5);
+    usage.fiveHour = row.five_hour_util;
+    if (row.five_hour_resets_at) usage.fiveHourResetsAt = row.five_hour_resets_at;
+  }
+  if (row.weekly_util != null) {
+    usage.weekly = toBucket(row.weekly_util, row.weekly_resets_at ?? "", 168);
+    usage.sevenDay = row.weekly_util;
+    if (row.weekly_resets_at) usage.sevenDayResetsAt = row.weekly_resets_at;
+  }
+  if (row.weekly_opus_util != null) {
+    usage.weeklyOpus = toBucket(row.weekly_opus_util, row.weekly_opus_resets_at ?? "", 168);
+  }
+  if (row.weekly_sonnet_util != null) {
+    usage.weeklySonnet = toBucket(row.weekly_sonnet_util, row.weekly_sonnet_resets_at ?? "", 168);
+  }
+  return usage;
+}
+
+/** Read the newest stored snapshot for one provider account, or undefined. */
+export function readStoredUsage(
+  providerId: string,
+  accountId: string,
+): (UsageInfo & { lastFetchedAt?: string }) | undefined {
+  const row = accountId === AMBIENT_ACCOUNT_KEY
+    ? getLatestLimitSnapshot(providerId)
+    : getLatestSnapshotForAccount(accountId, providerId);
+  return row ? snapshotToUsage(row) : undefined;
+}
+
+/**
+ * True when any stored bucket differs from the freshly fetched one.
+ *
+ * Utilizations compare with a tolerance rather than exactly: they are floats
+ * that round-trip through SQLite, and treating a last-digit wobble as a change
+ * would write a row on every single sweep.
+ */
+function hasChanged(usage: UsageInfo, last: LimitSnapshotRow | null): boolean {
+  if (!last) return true;
+  const moved = (fresh: number | null | undefined, stored: number | null) =>
+    fresh != null && (stored == null || Math.abs(fresh - stored) > 0.001);
+  if (moved(usage.session?.utilization, last.five_hour_util)) return true;
+  if (moved(usage.weekly?.utilization, last.weekly_util)) return true;
+  if (moved(usage.weeklyOpus?.utilization, last.weekly_opus_util)) return true;
+  if (moved(usage.weeklySonnet?.utilization, last.weekly_sonnet_util)) return true;
+  if (usage.session?.resetsAt && usage.session.resetsAt !== (last.five_hour_resets_at ?? "")) return true;
+  if (usage.weekly?.resetsAt && usage.weekly.resetsAt !== (last.weekly_resets_at ?? "")) return true;
+  return false;
+}
+
+/**
+ * Persist a freshly fetched value, writing a row only when a bucket moved.
+ *
+ * An account with nothing to report (every bucket absent) is not written at all:
+ * a row of nulls is indistinguishable from "never fetched" on read, so storing
+ * one buys nothing and only makes the history noisier.
+ */
+export function writeStoredUsage(providerId: string, accountId: string, usage: UsageInfo): void {
+  const hasAnyBucket = usage.session != null || usage.weekly != null
+    || usage.weeklyOpus != null || usage.weeklySonnet != null;
+  if (!hasAnyBucket) return;
+
+  const id = accountId === AMBIENT_ACCOUNT_KEY ? null : accountId;
+  const last = id ? getLatestSnapshotForAccount(id, providerId) : getLatestLimitSnapshot(providerId);
+  if (!hasChanged(usage, last)) {
+    if (id) touchSnapshotTimestamp(id, providerId);
+    return;
+  }
+  insertLimitSnapshot({
+    provider: providerId,
+    account_id: id,
+    five_hour_util: usage.session?.utilization ?? null,
+    five_hour_resets_at: usage.session?.resetsAt ?? null,
+    weekly_util: usage.weekly?.utilization ?? null,
+    weekly_resets_at: usage.weekly?.resetsAt ?? null,
+    weekly_opus_util: usage.weeklyOpus?.utilization ?? null,
+    weekly_opus_resets_at: usage.weeklyOpus?.resetsAt ?? null,
+    weekly_sonnet_util: usage.weeklySonnet?.utilization ?? null,
+    weekly_sonnet_resets_at: usage.weeklySonnet?.resetsAt ?? null,
+  });
+  cleanupOldLimitSnapshots();
+}

package/src/services/provider-usage/usage-source.ts

@@ -0,0 +1,82 @@
+import type { UsageInfo } from "../../types/chat.ts";
+
+/**
+ * What one provider must supply for its quota to be polled, cached, and stored
+ * by the shared usage layer.
+ *
+ * Everything scheduling-shaped — the background timer, the fetch timeout, the
+ * per-account cache, negative caching, staggering, in-flight de-duplication,
+ * writing to and reading back from the snapshot store — belongs to that layer,
+ * not here. A new provider implements the two required methods and inherits all
+ * of it; nothing in this interface knows about HTTP, JSON-RPC, or subprocesses.
+ */
+export interface ProviderUsageSource {
+  /** Matches the AIProvider id, and is what a snapshot row is scoped by. */
+  readonly providerId: string;
+
+  /**
+   * Accounts whose quota should be kept warm.
+   *
+   * An empty array is meaningful: it means this provider has no account store
+   * configured and reads a single ambient login instead, which the layer keys
+   * under {@link AMBIENT_ACCOUNT_KEY}.
+   */
+  listAccountIds(): string[];
+
+  /**
+   * Read one account's quota from the provider, live.
+   *
+   * Throw or reject on failure; do NOT return an empty object to signal one.
+   * The layer distinguishes the two: a rejection is cached briefly so a broken
+   * account cannot be retried on every request, while a resolved empty object
+   * is stored as a genuine "this account has no limits to report".
+   *
+   * `accountId` is {@link AMBIENT_ACCOUNT_KEY} when the provider has no
+   * account store.
+   */
+  fetch(accountId: string): Promise<UsageInfo>;
+
+  /**
+   * Skip this account on a background sweep without treating it as a failure —
+   * an expired token, a cooldown after a rate-limit, a login that cannot
+   * refresh. The last stored value stays readable.
+   */
+  shouldSkip?(accountId: string): boolean | Promise<boolean>;
+
+  /** Poll period override. Defaults to {@link DEFAULT_POLL_INTERVAL_MS}. */
+  readonly pollIntervalMs?: number;
+
+  /** Per-fetch ceiling override. Defaults to {@link FETCH_TIMEOUT_MS}. */
+  readonly fetchTimeoutMs?: number;
+}
+
+/** Cache/store key for a provider that reads one ambient login, not an account list. */
+export const AMBIENT_ACCOUNT_KEY = "";
+
+/** Both providers refresh on the same cadence; a source may override it. */
+export const DEFAULT_POLL_INTERVAL_MS = 300_000; // 5 min
+
+/** Gap between accounts inside one sweep, so a sweep is not a burst. */
+export const ACCOUNT_STAGGER_MS = 1_000;
+
+/**
+ * Ceiling on a single `fetch`. Codex spawns an app-server to answer, and that
+ * subprocess has been observed to accept the spawn and then never reply — with
+ * no ceiling the sweep waits forever, the HTTP route behind it never answers,
+ * and the subprocess is never closed. Claude's HTTP call has its own timeout
+ * but is covered here too, so one hung account cannot stall the whole sweep.
+ */
+export const FETCH_TIMEOUT_MS = 20_000;
+
+/** How long a resolved value is served from memory before a re-read. */
+export const USAGE_CACHE_TTL_MS = 300_000; // 5 min — matches the poll period
+
+/**
+ * How long a FAILURE is remembered.
+ *
+ * Short, because the cause is usually transient (a login being refreshed, a
+ * subprocess losing a race). Non-zero, because without it every request that
+ * misses re-attempts a fetch: for codex that meant spawning another app-server
+ * per request, and the ones that hung were never reaped.
+ */
+export const USAGE_FAILURE_TTL_MS = 30_000;

package/src/services/slash-discovery/builtin-commands.ts

@@ -42,6 +42,19 @@ export function getBuiltinSlashItems(): SlashItem[] {
   }));
 }
 
+/**
+ * Built-ins that work no matter which provider the tab is on.
+ *
+ * `handler: "sdk"` commands (`/compact`, `/cost`, `/model`, …) are passed
+ * straight through to the Claude SDK, so they do nothing in a session driven by
+ * another runtime. The `ppm` and `client` ones are intercepted before any
+ * provider sees them — by the PPM server and the web UI respectively — so they
+ * belong in every picker.
+ */
+export function getHostBuiltinSlashItems(): SlashItem[] {
+  return getBuiltinSlashItems().filter((item) => item.handler !== "sdk");
+}
+
 /** Look up a builtin command by name (or alias) */
 export function getBuiltinByName(name: string): BuiltinSlashCommand | undefined {
   const lower = name.toLowerCase();

package/src/services/slash-discovery/codex-skill-items.ts

@@ -0,0 +1,57 @@
+import { readFileSync, statSync } from "node:fs";
+import { extname } from "node:path";
+import type { CodexSkill } from "../../providers/codex-app-server/codex-protocol.ts";
+import type { SlashItem } from "./types.ts";
+
+/** Icons above this are not worth inlining into every picker response. */
+const MAX_ICON_BYTES = 32 * 1024;
+
+const ICON_MIME: Record<string, string> = {
+  ".svg": "image/svg+xml",
+  ".png": "image/png",
+  ".webp": "image/webp",
+  ".jpg": "image/jpeg",
+  ".jpeg": "image/jpeg",
+};
+
+/**
+ * Map the skills codex reported for a session into picker items.
+ *
+ * These are deliberately NOT merged with the disk-discovered Claude-side list.
+ * A codex session cannot run a Claude skill and vice versa, so mixing them
+ * offers the user entries that do nothing.
+ *
+ * Every item is marked `$`: codex activates a skill from a `$name` mention in
+ * the prompt, not from a leading slash.
+ */
+export function codexSkillsToSlashItems(skills: CodexSkill[]): SlashItem[] {
+  return skills.map((s) => ({
+    type: "skill" as const,
+    name: s.name,
+    description: s.interface?.shortDescription || s.description || "",
+    // "system" is codex's own bundled set; anything else the user put there.
+    scope: s.scope === "system" ? ("bundled" as const) : ("user" as const),
+    invokeSigil: "$" as const,
+    displayName: s.interface?.displayName,
+    iconDataUri: readIconDataUri(s.interface?.iconSmall),
+  }));
+}
+
+/**
+ * Read a skill icon into a data URI, or return undefined for anything that is
+ * missing, oversized, or of an unknown type.
+ *
+ * Never throws: a skill with a broken icon path still belongs in the picker,
+ * just without a picture.
+ */
+function readIconDataUri(path: string | undefined): string | undefined {
+  if (!path) return undefined;
+  const mime = ICON_MIME[extname(path).toLowerCase()];
+  if (!mime) return undefined;
+  try {
+    if (statSync(path).size > MAX_ICON_BYTES) return undefined;
+    return `data:${mime};base64,${readFileSync(path).toString("base64")}`;
+  } catch {
+    return undefined;
+  }
+}

package/src/services/slash-discovery/provider-skill-sigil.ts

@@ -0,0 +1,19 @@
+/**
+ * Swap the leading `/` of a typed command for the sigil the target runtime
+ * actually recognises.
+ *
+ * PPM's picker is slash-driven everywhere, but a provider may resolve its own
+ * skills differently — codex activates one from a `$name` mention in the prompt
+ * and treats `/name` as ordinary text, so a picked skill would appear to be
+ * ignored. Only the sigil changes; arguments after the name are untouched.
+ *
+ * The rewrite is deliberately conservative: the first word must match a skill
+ * the runtime reported, so a slash command the runtime does not own (a PPM
+ * built-in, a typo, a bare `/`) is returned exactly as typed.
+ */
+export function applySkillSigil(content: string, skillNames: Set<string>, sigil: string): string {
+  const match = content.match(/^\/(\S+)/);
+  const name = match?.[1];
+  if (!name || !skillNames.has(name)) return content;
+  return sigil + content.slice(1);
+}

package/src/services/slash-discovery/types.ts

@@ -35,6 +35,25 @@ export interface SlashItem {
   tools?: string[];
   /** Built-in only: which layer executes the command */
   handler?: SlashHandler;
+  /**
+   * Sigil the runtime expects when the item is invoked. Absent means `/`, which
+   * is every Claude-side skill and command. Codex resolves its skills from a
+   * `$name` mention inside the prompt instead, so an item carrying `"$"` must be
+   * sent with that prefix or codex treats it as ordinary prose.
+   */
+  invokeSigil?: "/" | "$";
+  /** Pretty label the runtime supplies for itself, when it does (codex system skills). */
+  displayName?: string;
+  /**
+   * Runtime-supplied icon, inlined as a data URI rather than a URL.
+   *
+   * The source files sit inside the codex account home, which the credential
+   * path guard refuses on every generic file route — correctly, since
+   * `auth.json` is a sibling. Inlining keeps that door shut: the icon never
+   * needs a servable path, and the client never sends one back. They are small
+   * enough for this to be cheap (under 3 KB each).
+   */
+  iconDataUri?: string;
 }
 
 export interface SkillRoot {