Fix workspace-scoped Codex skill discovery

BRANCH_DETAILS.md

@@ -0,0 +1,62 @@
+# Codex Workspace Skill Loading
+
+Fix Codex repo-local skill discovery in the composer by resolving skills for the active project/worktree cwd, instead of relying on the global provider status snapshot.
+
+Expected behavior:
+
+- Repo-local Codex skills for the active workspace appear in the `$` skill picker.
+- The server exposes a workspace-aware `server.listProviderSkills` path and validates enabled Codex skill-listing requests against the requested cwd.
+- The server routes skill listing through a bounded request lister that coalesces concurrent requests for the same provider/cwd, limits cross-workspace concurrency, and applies a short TTL so reconnects or repeated composer renders do not repeatedly spawn Codex app-server probes.
+- The Codex provider requests `skills/list` with the current workspace cwd, times out hung app-server probes, and terminates the probe process when a timeout occurs.
+- Provider skill-list failures preserve structured reason, operation, provider instance, normalized cwd, and bounded cause diagnostics for missing providers, invalid cwd, settings failures, Codex home preparation, probe timeouts, and probe failures while keeping stable user-facing messages. Raw thrown values are not sent directly to clients; the server keeps a small plain diagnostic shape so file paths, process output, and unexpected objects do not expand the wire payload.
+- Non-Codex or disabled providers keep returning provider snapshot skills instead of failing workspace skill search.
+- The client runtime keys provider-skill query state by environment, provider instance, and cwd, with a bounded stale window so reconnects refresh workspace-local skills without reusing another workspace's snapshot. Client-side fallback skill changes do not refresh the workspace query or respawn Codex skill probes.
+- Web workspace-skill lookup follows the route environment's connection state. While disconnected, it does not start an RPC, retains only verified skills for the same environment/provider/cwd across lazy menu close/reopen cycles, otherwise falls back to provider snapshot skills with a non-pending reconnect error, and resumes the workspace refresh when the environment reconnects.
+- The composer loads workspace skills lazily: it starts workspace skill discovery when the `$` skill menu is active or the prompt already contains a complete `$skill` token, rather than probing on every empty composer mount. It preserves already loaded repo-local skills while refreshing the same workspace, falls back to provider snapshot skills when a settled workspace lookup returns no skills or errors, keeps structured lookup errors visible alongside those fallback skills on web and mobile, and clears stale repo-local skills during workspace switches or settled no-data states.
+- The conversation timeline renders sent user prompts against the same workspace-aware skill list as the composer, so repo-local `$skill-name` references display with the same skill chip treatment as user-level skills. Timeline lookup stays disabled until a sent user prompt contains a complete skill token, including one at the end of the message, so an empty draft does not probe Codex merely to decorate nonexistent messages.
+- The shared client-runtime policy also drives mobile thread composers and feeds. Mobile shows loading and structured error feedback, refreshes an already-open `$` menu when skills arrive, decorates complete skill references, and prevents stale successful results from surviving a failed refresh.
+- New-task drafts request workspace skills lazily only after a complete `$skill` reference. Local drafts resolve the selected checkout or project root, while future-worktree drafts deliberately have no cwd and use provider snapshots until the target directory exists.
+
+Primary files:
+
+- `apps/server/src/ws.ts`
+- `apps/server/src/provider/ProviderSkillsLister.ts`
+- `apps/server/src/provider/Layers/CodexProvider.ts`
+- `apps/web/src/components/ChatView.tsx`
+- `apps/web/src/components/chat/ChatComposer.tsx`
+- `apps/web/src/components/chat/MessagesTimeline.tsx`
+- `apps/web/src/lib/providerWorkspaceSkillsState.ts`
+- `apps/mobile/src/state/providerWorkspaceSkillsState.ts`
+- `apps/mobile/src/features/threads/new-task-provider-skills.ts`
+- `apps/mobile/src/features/threads/thread-composer-skill-items.ts`
+- `packages/client-runtime/src/state/providerWorkspaceSkills.ts`
+- `packages/contracts/src/server.ts`
+- `packages/client-runtime/src/state/server.ts`
+
+Relevant tests live in:
+
+- `apps/server/src/server.test.ts`
+- `apps/server/src/provider/ProviderSkillsLister.test.ts`
+- `apps/server/src/provider/Layers/CodexProvider.test.ts`
+- `apps/server/src/provider/Layers/CursorProvider.test.ts`
+- `apps/server/src/provider/Layers/GrokProvider.test.ts`
+- `apps/web/src/components/chat/MessagesTimeline.test.tsx`
+- `apps/web/src/lib/providerWorkspaceSkillsState.test.ts`
+- `apps/mobile/src/features/threads/new-task-provider-skills.test.ts`
+- `apps/mobile/src/features/threads/thread-composer-skill-items.test.ts`
+- `packages/client-runtime/src/state/providerWorkspaceSkills.test.ts`
+- `packages/client-runtime/src/state/runtime.test.ts`
+
+Useful focused commands:
+
+```sh
+(cd apps/server && pnpm exec vp test run --passWithNoTests src/provider/ProviderSkillsLister.test.ts src/provider/Layers/CodexProvider.test.ts src/provider/Layers/CursorProvider.test.ts src/provider/Layers/GrokProvider.test.ts)
+(cd apps/web && pnpm exec vp test run --passWithNoTests --project unit src/lib/providerWorkspaceSkillsState.test.ts)
+(cd apps/mobile && pnpm exec vp test run --passWithNoTests src/features/threads/new-task-provider-skills.test.ts src/features/threads/thread-composer-skill-items.test.ts)
+(cd packages/client-runtime && pnpm exec vp test run --passWithNoTests src/state/providerWorkspaceSkills.test.ts)
+```
+
+## Development Ports
+
+- Web: `5735`
+- Server/WebSocket: `13775`

apps/mobile/modules/t3-markdown-text/package.json

@@ -26,6 +26,7 @@
     "./types": "./src/SelectableMarkdownText.types.ts"
   },
   "peerDependencies": {
+    "@t3tools/shared": "workspace:*",
     "expo-asset": "*",
     "expo-clipboard": "*",
     "expo-haptics": "*",

apps/mobile/modules/t3-markdown-text/src/nativeMarkdownText.ts

@@ -1,4 +1,5 @@
 import type { MarkdownNode } from "react-native-nitro-markdown/headless";
+import { parseInlineSkillTokens } from "@t3tools/shared/skillInlineTokens";
 
 import type { SelectableMarkdownSkill } from "./SelectableMarkdownText.types";
 import { resolveMarkdownLinkPresentation, type MarkdownFileIcon } from "./markdownLinks";
@@ -184,8 +185,6 @@ function appendRun(
   return runs;
 }
 
-const SKILL_TOKEN_REGEX = /(^|\s)\$([a-zA-Z][a-zA-Z0-9:_-]*)(?=\s|$)/g;
-
 function formatSkillLabel(skill: SelectableMarkdownSkill): string {
   const displayName = skill.displayName?.trim();
   if (displayName) {
@@ -216,14 +215,13 @@ function decorateSkillRuns(
 
     let cursor = 0;
     let matched = false;
-    for (const match of run.text.matchAll(SKILL_TOKEN_REGEX)) {
-      const prefix = match[1] ?? "";
-      const name = match[2] ?? "";
+    for (const match of parseInlineSkillTokens(run.text)) {
+      const { name } = match;
       const skill = skillByName.get(name);
       if (!skill) {
         continue;
       }
-      const start = (match.index ?? 0) + prefix.length;
+      const { start } = match;
       const end = start + name.length + 1;
       if (start > cursor) {
         decorated.push({ ...run, text: run.text.slice(cursor, start) });

apps/mobile/src/features/threads/ComposerCommandPopover.tsx

@@ -42,6 +42,7 @@ interface ComposerCommandPopoverProps {
   readonly items: ReadonlyArray<ComposerCommandItem>;
   readonly triggerKind: ComposerTriggerKind | null;
   readonly isLoading: boolean;
+  readonly error: string | null;
   readonly onSelect: (item: ComposerCommandItem) => void;
 }
 
@@ -181,6 +182,13 @@ export const ComposerCommandPopover = memo(function ComposerCommandPopover(
           </Text>
         </View>
       ) : null}
+      {props.error ? (
+        <View className="px-3.5 py-2.5">
+          <Text className="text-xs text-danger-foreground" numberOfLines={3}>
+            {props.error}
+          </Text>
+        </View>
+      ) : null}
       {props.items.length > 0 ? (
         <ScrollView
           className="max-h-[180px]"
@@ -196,7 +204,7 @@ export const ComposerCommandPopover = memo(function ComposerCommandPopover(
             />
           ))}
         </ScrollView>
-      ) : (
+      ) : props.error ? null : (
         <View className="px-3.5 py-2.5">
           <Text className="text-xs text-foreground-tertiary">
             {emptyText(props.triggerKind, props.isLoading)}

apps/mobile/src/features/threads/ThreadComposer.tsx

@@ -7,6 +7,7 @@ import type {
   ProviderInteractionMode,
   RuntimeMode,
   ServerConfig as T3ServerConfig,
+  ServerProviderSkill,
 } from "@t3tools/contracts";
 import {
   detectComposerTrigger,
@@ -56,11 +57,6 @@ import type { DraftComposerImageAttachment } from "../../lib/composerImages";
 import { buildModelOptions, groupByProvider } from "../../lib/modelOptions";
 import { useScaledTextRole } from "../settings/appearance/useScaledTextRole";
 import type { RemoteClientConnectionState } from "../../lib/connection";
-import {
-  insertRankedSearchResult,
-  normalizeSearchQuery,
-  scoreQueryMatch,
-} from "@t3tools/shared/searchRanking";
 import {
   applyProviderOptionMenuEvent,
   buildProviderOptionMenuActions,
@@ -69,6 +65,7 @@ import {
 } from "../../lib/providerOptions";
 import { useComposerPathSearch } from "../../state/use-composer-path-search";
 import { ComposerCommandPopover, type ComposerCommandItem } from "./ComposerCommandPopover";
+import { buildComposerSkillItems } from "./thread-composer-skill-items";
 
 /**
  * Height of the collapsed composer (pill + vertical padding, excluding safe-area inset).
@@ -99,6 +96,9 @@ export interface ThreadComposerProps {
   readonly threadSyncPhase?: "loading" | "syncing" | null;
   readonly selectedThread: OrchestrationThreadShell;
   readonly serverConfig: T3ServerConfig | null;
+  readonly workspaceSkills: ReadonlyArray<ServerProviderSkill>;
+  readonly workspaceSkillsIsPending: boolean;
+  readonly workspaceSkillsError: string | null;
   readonly queueCount: number;
   readonly activeThreadBusy: boolean;
   readonly environmentId: EnvironmentId;
@@ -412,86 +412,7 @@ export const ThreadComposer = memo(function ThreadComposer(props: ThreadComposer
     }
 
     if (composerTrigger.kind === "skill") {
-      const enabledSkills = (selectedProviderStatus?.skills ?? []).filter((s) => s.enabled);
-      const normalizedQuery = normalizeSearchQuery(composerTrigger.query, {
-        trimLeadingPattern: /^\$+/,
-      });
-
-      if (!normalizedQuery) {
-        return enabledSkills.slice(0, 20).map((skill) => ({
-          id: `skill:${skill.name}`,
-          type: "skill" as const,
-          skill,
-          label: skill.displayName ?? skill.name,
-          description: skill.shortDescription ?? skill.description ?? "",
-        }));
-      }
-
-      const ranked: Array<{
-        item: (typeof enabledSkills)[number];
-        score: number;
-        tieBreaker: string;
-      }> = [];
-      for (const skill of enabledSkills) {
-        const displayLabel = (skill.displayName ?? skill.name).toLowerCase();
-        const scores = [
-          scoreQueryMatch({
-            value: skill.name.toLowerCase(),
-            query: normalizedQuery,
-            exactBase: 0,
-            prefixBase: 2,
-            boundaryBase: 4,
-            includesBase: 6,
-            fuzzyBase: 100,
-            boundaryMarkers: ["-", "_", "/"],
-          }),
-          scoreQueryMatch({
-            value: displayLabel,
-            query: normalizedQuery,
-            exactBase: 1,
-            prefixBase: 3,
-            boundaryBase: 5,
-            includesBase: 7,
-            fuzzyBase: 110,
-          }),
-          scoreQueryMatch({
-            value: skill.shortDescription?.toLowerCase() ?? "",
-            query: normalizedQuery,
-            exactBase: 20,
-            prefixBase: 22,
-            boundaryBase: 24,
-            includesBase: 26,
-          }),
-          scoreQueryMatch({
-            value: skill.description?.toLowerCase() ?? "",
-            query: normalizedQuery,
-            exactBase: 30,
-            prefixBase: 32,
-            boundaryBase: 34,
-            includesBase: 36,
-          }),
-        ].filter((s): s is number => s !== null);
-
-        if (scores.length > 0) {
-          insertRankedSearchResult(
-            ranked,
-            {
-              item: skill,
-              score: Math.min(...scores),
-              tieBreaker: `${displayLabel}\u0000${skill.name}`,
-            },
-            20,
-          );
-        }
-      }
-
-      return ranked.map(({ item: skill }) => ({
-        id: `skill:${skill.name}`,
-        type: "skill" as const,
-        skill,
-        label: skill.displayName ?? skill.name,
-        description: skill.shortDescription ?? skill.description ?? "",
-      }));
+      return buildComposerSkillItems(props.workspaceSkills, composerTrigger.query);
     }
 
     if (composerTrigger.kind === "path") {
@@ -509,7 +430,7 @@ export const ThreadComposer = memo(function ThreadComposer(props: ThreadComposer
     }
 
     return [];
-  }, [composerTrigger, pathSearch.entries, selectedProviderStatus]);
+  }, [composerTrigger, pathSearch.entries, props.workspaceSkills, selectedProviderStatus]);
 
   // ── Handle command selection ──────────────────────────────
   const { onChangeDraftMessage, onUpdateInteractionMode, draftMessage, onSendMessage } = props;
@@ -724,12 +645,17 @@ export const ThreadComposer = memo(function ThreadComposer(props: ThreadComposer
         layout={COMPOSER_LAYOUT_TRANSITION}
         style={{ maxWidth: props.contentMaxWidth }}
       >
-        {composerTrigger && composerMenuItems.length > 0 ? (
+        {composerTrigger && (composerMenuItems.length > 0 || composerTrigger.kind === "skill") ? (
           <View className="absolute inset-x-0 bottom-full z-10 mb-2">
             <ComposerCommandPopover
               items={composerMenuItems}
               triggerKind={composerTrigger.kind}
-              isLoading={pathSearch.isPending}
+              isLoading={
+                composerTrigger.kind === "skill"
+                  ? props.workspaceSkillsIsPending
+                  : pathSearch.isPending
+              }
+              error={composerTrigger.kind === "skill" ? props.workspaceSkillsError : null}
               onSelect={handleCommandSelect}
             />
           </View>
@@ -783,7 +709,7 @@ export const ThreadComposer = memo(function ThreadComposer(props: ThreadComposer
               ref={inputRef}
               multiline
               value={props.draftMessage}
-              skills={selectedProviderStatus?.skills ?? []}
+              skills={props.workspaceSkills}
               selection={composerSelection}
               onChangeText={props.onChangeDraftMessage}
               onSelectionChange={handleSelectionChange}

apps/mobile/src/features/threads/ThreadDetailScreen.tsx

@@ -12,6 +12,7 @@ import type {
   ProviderInteractionMode,
   RuntimeMode,
   ServerConfig as T3ServerConfig,
+  ServerProviderSkill,
   ThreadId,
 } from "@t3tools/contracts";
 import * as Haptics from "expo-haptics";
@@ -41,6 +42,7 @@ import {
 } from "./ThreadComposer";
 import { ThreadFeed } from "./ThreadFeed";
 import type { ThreadContentPresentation } from "./threadContentPresentation";
+import { useProviderWorkspaceSkills } from "../../state/providerWorkspaceSkillsState";
 
 export interface ThreadDetailScreenProps {
   readonly selectedThread: OrchestrationThreadShell;
@@ -225,12 +227,19 @@ export const ThreadDetailScreen = memo(function ThreadDetailScreen(props: Thread
   const contentMaxWidth = isSplitLayout ? CHAT_CONTENT_MAX_WIDTH : undefined;
   const selectedInstanceId = props.selectedThread.modelSelection.instanceId;
   useStreamingHaptics(props.selectedThread.id, props.selectedThreadFeed);
-  const selectedProviderSkills = useMemo(
+  const selectedProviderFallbackSkills = useMemo<ReadonlyArray<ServerProviderSkill>>(
     () =>
       props.serverConfig?.providers.find((provider) => provider.instanceId === selectedInstanceId)
         ?.skills ?? [],
     [props.serverConfig, selectedInstanceId],
   );
+  const selectedProviderWorkspaceSkills = useProviderWorkspaceSkills({
+    environmentId: props.environmentId,
+    instanceId: selectedInstanceId,
+    cwd: props.threadCwd ?? props.projectWorkspaceRoot,
+    enabled: true,
+    fallbackSkills: selectedProviderFallbackSkills,
+  });
 
   useLayoutEffect(() => {
     selectedThreadKeyRef.current = selectedThreadKey;
@@ -370,7 +379,7 @@ export const ThreadDetailScreen = memo(function ThreadDetailScreen(props: Thread
             layoutVariant={layoutVariant}
             usesAutomaticContentInsets={props.usesAutomaticContentInsets}
             onHeaderMaterialVisibilityChange={props.onHeaderMaterialVisibilityChange}
-            skills={selectedProviderSkills}
+            skills={selectedProviderWorkspaceSkills.skills}
           />
         </View>
       ) : (
@@ -428,6 +437,9 @@ export const ThreadDetailScreen = memo(function ThreadDetailScreen(props: Thread
               threadSyncPhase={threadSyncPhase}
               selectedThread={props.selectedThread}
               serverConfig={props.serverConfig}
+              workspaceSkills={selectedProviderWorkspaceSkills.skills}
+              workspaceSkillsIsPending={selectedProviderWorkspaceSkills.isPending}
+              workspaceSkillsError={selectedProviderWorkspaceSkills.error}
               queueCount={props.selectedThreadQueueCount}
               activeThreadBusy={props.activeThreadBusy}
               environmentId={props.environmentId}