sailfork / t3code-github / packages/ client-runtime/ src/ providerSkills.ts

import {
  type EnvironmentId,
  isProviderWorkspaceSnapshotCurrent,
  PROVIDER_WORKSPACE_SNAPSHOT_TTL_MS,
  type ProviderInstanceId,
  type ServerProvider,
  type ServerProviderSkill,
  type ServerProviderSlashCommand,
} from "@t3tools/contracts";
import { Atom } from "effect/reactivity";

import { deadlineStore } from "./clock.ts";
import { type AtomCommand, runAtomCommand } from "./state/runtime.ts";

export type ProviderSkillSourceKind = "app" | "repo" | "project" | "personal" | "system" | "other";

function normalizePathSeparators(pathValue: string): string {
  return pathValue.replaceAll("\\", "/");
}

export function dedupeProviderSkillsByName(
  skills: ReadonlyArray<ServerProviderSkill>,
): ServerProviderSkill[] {
  const seenNames = new Set<string>();
  return skills.filter((skill) => {
    const normalizedName = skill.name.trim().toLowerCase();
    if (seenNames.has(normalizedName)) {
      return false;
    }
    seenNames.add(normalizedName);
    return true;
  });
}

/**
 * Exclude disabled and agent-only skills (Claude Code's `user-invocable: false`).
 * Skills the agent cannot start on its own can still be invoked by users in the provider's native form.
 */
export function isProviderSkillUserInvocable(
  skill: Pick<ServerProviderSkill, "enabled" | "userInvocable">,
): boolean {
  return skill.enabled && skill.userInvocable !== false;
}

export function getProviderSkillsForSlashMenu(
  skills: ReadonlyArray<ServerProviderSkill>,
  showSkillsInSlashMenu: boolean,
): ServerProviderSkill[] {
  return showSkillsInSlashMenu
    ? dedupeProviderSkillsByName(skills.filter(isProviderSkillUserInvocable))
    : [];
}

export function getProviderSlashCommandsForSlashMenu(
  slashCommands: ReadonlyArray<ServerProviderSlashCommand>,
  visibleSkills: ReadonlyArray<ServerProviderSkill>,
): ServerProviderSlashCommand[] {
  const skillNames = new Set(visibleSkills.map((skill) => skill.name.trim().toLowerCase()));
  return slashCommands.filter((command) => !skillNames.has(command.name.trim().toLowerCase()));
}

export function resolveProviderSkillSourceKind(
  skill: Pick<ServerProviderSkill, "path" | "scope">,
): ProviderSkillSourceKind {
  const normalizedPath = normalizePathSeparators(skill.path);
  if (normalizedPath.includes("/.codex/plugins/") || normalizedPath.includes("/.agents/plugins/")) {
    return "app";
  }

  const normalizedScope = skill.scope?.trim().toLowerCase();
  switch (normalizedScope) {
    case "repo":
    case "repository":
      return "repo";
    case "project":
    case "workspace":
    case "local":
      return "project";
    case "user":
    case "personal":
      return "personal";
    case "system":
      return "system";
    case undefined:
    case "":
      return "other";
    default:
      return "other";
  }
}

function resolveProviderWorkspaceSnapshot(
  provider: ServerProvider,
  cwd: string | null | undefined,
) {
  if (!cwd) return undefined;
  return provider.workspaceSnapshots?.find((snapshot) => snapshot.cwd === cwd);
}

export function hasCompleteProviderWorkspaceSnapshot(
  provider: ServerProvider | null | undefined,
  cwd: string | null | undefined,
): boolean {
  const snapshot = provider && resolveProviderWorkspaceSnapshot(provider, cwd);
  return Boolean(snapshot && !snapshot.slashCommandsPending);
}

function hasCurrentProviderWorkspaceSnapshot(
  provider: ServerProvider | null | undefined,
  cwd: string | null | undefined,
  nowMs: number,
): boolean {
  const snapshot = provider && resolveProviderWorkspaceSnapshot(provider, cwd);
  return Boolean(
    snapshot &&
    !snapshot.slashCommandsPending &&
    isProviderWorkspaceSnapshotCurrent(snapshot, nowMs),
  );
}

export function resolveProviderSkillsForCwd(
  provider: ServerProvider,
  cwd: string | null | undefined,
): ServerProvider["skills"] {
  return resolveProviderWorkspaceSnapshot(provider, cwd)?.skills ?? provider.skills;
}

export function resolveProviderSlashCommandsForCwd(
  provider: ServerProvider,
  cwd: string | null | undefined,
): ServerProvider["slashCommands"] {
  return resolveProviderWorkspaceSnapshot(provider, cwd)?.slashCommands ?? provider.slashCommands;
}

const WORKSPACE_SNAPSHOT_RETRY_COOLDOWN_MS = 10_000;
// A cwd that never scans, such as a deleted worktree, would otherwise retry forever.
const WORKSPACE_SNAPSHOT_MAX_ATTEMPTS = 3;

export interface ProviderWorkspaceSnapshotRefreshState {
  /**
   * When the last scan was requested. A request inside the TTL is not
   * repeated, so a client clock ahead of the server's cannot loop rescans.
   */
  readonly requestedAt: number | null;
  /** A failed scan is not retried before this time. */
  readonly retryNotBefore: number | null;
  /** Failed scans within the current request TTL. */
  readonly failedAttempts: number;
  readonly hadSnapshot: boolean;
  /** The server published a partial snapshot and is still discovering. */
  readonly snapshotPending: boolean;
}

const initialProviderWorkspaceSnapshotRefreshState: ProviderWorkspaceSnapshotRefreshState = {
  requestedAt: null,
  retryNotBefore: null,
  failedAttempts: 0,
  hadSnapshot: false,
  snapshotPending: false,
};

/**
 * Decides whether a composer looking at `cwd` should ask the server to rescan
 * the provider's workspace, and when to look again if a retry is due while the
 * server still reports the scan as pending.
 */
function planProviderWorkspaceSnapshotRefresh(
  previous: ProviderWorkspaceSnapshotRefreshState,
  provider: ServerProvider | null | undefined,
  cwd: string,
  now: number,
): {
  readonly state: ProviderWorkspaceSnapshotRefreshState;
  readonly refresh: boolean;
  readonly recheckAt: number | null;
} {
  const hasSnapshot = hasCompleteProviderWorkspaceSnapshot(provider, cwd);
  const pending =
    (provider && resolveProviderWorkspaceSnapshot(provider, cwd)?.slashCommandsPending) === true;
  // Losing a snapshot (the server dropped it) lifts both the TTL and the retry
  // cooldown so the scan happens at once.
  const lost = previous.hadSnapshot && !hasSnapshot;
  const requestedAt = lost ? null : previous.requestedAt;
  const retryNotBefore =
    lost || (previous.retryNotBefore !== null && now >= previous.retryNotBefore)
      ? null
      : previous.retryNotBefore;
  const state = {
    requestedAt,
    retryNotBefore,
    failedAttempts:
      lost || (requestedAt !== null && now - requestedAt >= PROVIDER_WORKSPACE_SNAPSHOT_TTL_MS)
        ? 0
        : previous.failedAttempts,
    hadSnapshot: hasSnapshot,
    snapshotPending: pending,
  };
  const refresh =
    (requestedAt === null || now - requestedAt >= PROVIDER_WORKSPACE_SNAPSHOT_TTL_MS) &&
    !hasCurrentProviderWorkspaceSnapshot(provider, cwd, now) &&
    retryNotBefore === null;
  if (refresh) {
    return { state: { ...state, requestedAt: now }, refresh: true, recheckAt: null };
  }
  return { state, refresh: false, recheckAt: pending ? retryNotBefore : null };
}

/**
 * A scan that failed, or finished without a complete snapshot, cools down
 * before retrying. After the last attempt the request marker stays, so only
 * the TTL (or a snapshot loss) lets the next scan through.
 */
function failProviderWorkspaceSnapshotRefresh(
  state: ProviderWorkspaceSnapshotRefreshState,
  requestedAt: number,
  now: number,
): ProviderWorkspaceSnapshotRefreshState {
  // A newer request, or a snapshot loss, already superseded this one.
  if (state.requestedAt !== requestedAt) return state;
  const failedAttempts = state.failedAttempts + 1;
  if (failedAttempts >= WORKSPACE_SNAPSHOT_MAX_ATTEMPTS) return { ...state, failedAttempts };
  return {
    ...state,
    requestedAt: null,
    retryNotBefore: now + WORKSPACE_SNAPSHOT_RETRY_COOLDOWN_MS,
    failedAttempts,
  };
}

/**
 * A scan is in flight, or the server is still discovering, for a cwd without a
 * complete snapshot, so its skills and commands may still arrive. A failed scan
 * clears `requestedAt`, and exhausted attempts end it, so this cannot stay true
 * for a scan that will not finish.
 */
export function isProviderWorkspaceSnapshotScanning(
  state: ProviderWorkspaceSnapshotRefreshState | undefined,
): boolean {
  return (
    state !== undefined &&
    (state.requestedAt !== null || state.snapshotPending) &&
    !state.hadSnapshot &&
    state.failedAttempts < WORKSPACE_SNAPSHOT_MAX_ATTEMPTS
  );
}

type WorkspaceSnapshotStatus = "absent" | "pending" | "complete";

function resolveWorkspaceSnapshotStatus(
  provider: ServerProvider | undefined,
  cwd: string,
): WorkspaceSnapshotStatus {
  const snapshot = provider && resolveProviderWorkspaceSnapshot(provider, cwd);
  if (!snapshot) return "absent";
  return snapshot.slashCommandsPending ? "pending" : "complete";
}

interface ProviderWorkspaceSnapshotRefreshTarget {
  readonly environmentId: EnvironmentId;
  readonly instanceId: ProviderInstanceId;
  readonly cwd: string;
}

/**
 * Keeps one environment/provider/cwd workspace snapshot fresh while mounted:
 * reading scans when it is missing or stale, and refreshing re-checks (the
 * composer does as the user types). It owns the retry timer, so the timer dies
 * with the last subscriber.
 */
export function createProviderWorkspaceSnapshotRefreshAtomFamily(input: {
  readonly providers: (
    environmentId: EnvironmentId,
  ) => Atom.Atom<ReadonlyArray<ServerProvider> | null>;
  readonly refreshProviders: AtomCommand<
    {
      readonly environmentId: EnvironmentId;
      readonly input: { readonly instanceId: ProviderInstanceId; readonly cwd: string };
    },
    { readonly providers: ReadonlyArray<ServerProvider> },
    unknown
  >;
}) {
  // Plain-object keys compare structurally (Effect `Equal`/`Hash`).
  const family = Atom.family((target: ProviderWorkspaceSnapshotRefreshTarget) => {
    const { environmentId, instanceId, cwd } = target;
    const key = `${environmentId}:${instanceId}:${cwd}`;
    const findProvider = (providers: ReadonlyArray<ServerProvider> | null) =>
      providers?.find((provider) => provider.instanceId === instanceId);
    const statusAtom = Atom.make((get) =>
      resolveWorkspaceSnapshotStatus(findProvider(get(input.providers(environmentId))), cwd),
    ).pipe(Atom.withLabel(`provider-workspace-snapshot-status:${key}`));
    type Update = (
      state: ProviderWorkspaceSnapshotRefreshState,
    ) => ProviderWorkspaceSnapshotRefreshState;
    const refreshAtom: Atom.Writable<ProviderWorkspaceSnapshotRefreshState, Update> = Atom.writable(
      (get): ProviderWorkspaceSnapshotRefreshState => {
        get(statusAtom);
        // `once`: unrelated provider updates must not trigger a check.
        const provider = findProvider(get.once(input.providers(environmentId)));
        // @effect-diagnostics-next-line globalDate:off
        const now = Date.now();
        const previous = get.self<ProviderWorkspaceSnapshotRefreshState>();
        const plan = planProviderWorkspaceSnapshotRefresh(
          previous._tag === "Some" ? previous.value : initialProviderWorkspaceSnapshotRefreshState,
          provider,
          cwd,
          now,
        );
        if (plan.recheckAt !== null) {
          get.addFinalizer(deadlineStore(plan.recheckAt).subscribe(() => get.refreshSelf()));
        }
        if (!plan.refresh) return plan.state;
        const registry = get.registry;
        // Outlives this build on purpose: a rebuild must not drop the retry.
        // Once nothing subscribes, the retry state dies with the node; writing
        // would recreate and rebuild it, which scans again with no subscriber.
        const retryLater = () => {
          const node = registry.getNodes().get(refreshAtom);
          if (node === undefined || node.canBeRemoved) return;
          registry.set(refreshAtom, (state) =>
            // @effect-diagnostics-next-line globalDate:off
            failProviderWorkspaceSnapshotRefresh(state, now, Date.now()),
          );
        };
        void runAtomCommand(
          registry,
          input.refreshProviders,
          { environmentId, input: { instanceId, cwd } },
          { reportFailure: false },
        ).then((result) => {
          const refreshedProvider =
            result._tag === "Success" ? findProvider(result.value.providers) : undefined;
          const snapshot =
            refreshedProvider && resolveProviderWorkspaceSnapshot(refreshedProvider, cwd);
          // A new server timestamp proves progress even when the client clock is ahead.
          // @effect-diagnostics-next-line globalDate:off
          const completedAt = Date.now();
          const refreshed =
            hasCompleteProviderWorkspaceSnapshot(refreshedProvider, cwd) &&
            (hasCurrentProviderWorkspaceSnapshot(refreshedProvider, cwd, completedAt) ||
              snapshot?.checkedAt !==
                (provider && resolveProviderWorkspaceSnapshot(provider, cwd))?.checkedAt);
          if (!refreshed) retryLater();
        }, retryLater);
        return plan.state;
      },
      (ctx, update: Update) => {
        ctx.setSelf(update(ctx.get(refreshAtom)));
        ctx.refreshSelf();
      },
    ).pipe(Atom.withLabel(`provider-workspace-snapshot-refresh:${key}`));
    return refreshAtom;
  });
  return (
    target: ProviderWorkspaceSnapshotRefreshTarget,
  ): Atom.Atom<ProviderWorkspaceSnapshotRefreshState> =>
    family({ environmentId: target.environmentId, instanceId: target.instanceId, cwd: target.cwd });
}