feat: offer plugin actions in the palette, slash menu and thread menus

.github/scripts/ci-changes.cjs

@@ -27,6 +27,8 @@ const EXTRA_OWNERS = [
   [/^native\/browser-secret\//, ["@t3tools/desktop"]],
   [/^native\/kde-snap-shot\//, ["@t3tools/desktop"]],
   [/^native\/libghostty-vt\//, ["@t3tools/web"]],
+  // apps/server/src/cloud/ConnectReachability.test.ts checks the guide's headings.
+  [/^docs\/user\/t3-connect-troubleshooting\.md$/, ["t3"]],
 ];
 const RUST = /^native\/(resource-monitor|kde-snap-shot|hyprland-snap-shot)\//;
 
@@ -92,11 +94,11 @@ function readWorkspace() {
 
 // [] means inert; null means unknown and requires every job.
 function ownersOf(file, packages) {
-  if (INERT.some((pattern) => pattern.test(file))) return [];
+  const extra = EXTRA_OWNERS.flatMap(([pattern, names]) => (pattern.test(file) ? names : []));
+  if (INERT.some((pattern) => pattern.test(file))) return extra;
   // A manifest can change dependencies or versions other packages read.
   if (path.posix.basename(file) === "package.json") return null;
   if (RUNS_EVERYTHING.some((pattern) => pattern.test(file))) return null;
-  const extra = EXTRA_OWNERS.flatMap(([pattern, names]) => (pattern.test(file) ? names : []));
   // scripts/build-desktop-artifact.test.ts reads the crates' sources.
   if (RUST.test(file)) return ["@t3tools/scripts", ...extra];
 

.macroscope/check-run-agents/ui-consistency.md

@@ -44,7 +44,7 @@ The reference for how this codebase wants UI built is the composer banner system
 
 - `ComposerBanner.tsx` exports one object of small slot components (`Root`, `Row`, `Icon`, `Content`, `Actions`, `Dismiss`, `Children`, and so on). Each slot owns its own Tailwind classes, exposes a `data-slot` attribute, takes `className` and spreads the rest of its props, and uses `cn` so callers can adjust without overriding. Variants and density are props on `Root`, not ad hoc class strings at call sites. Where a slot needs a real control it renders `Button` from `ui/` rather than a styled `<button>`.
 - `ComposerBannerStack.tsx` composes those slots into the ordered stack and owns only stack behavior (priority, expand and collapse, dismiss transitions).
-- Consumers such as `ComposerActivityStatus.tsx`, `ComposerStashBadge.tsx`, and `ComposerPlanFollowUpBanner.tsx` are a few lines of `<ComposerBanner.Row><ComposerBanner.Icon/><ComposerBanner.Content>…` with no styling of their own.
+- Consumers such as `ComposerPlanFollowUpBanner.tsx` are a few lines of `<ComposerBanner.Row><ComposerBanner.Icon/><ComposerBanner.Content>…` and style only their own content.
 
 Hold new and changed UI to that shape:
 

apps/desktop/src/snapShot/DesktopSnapShot.test.ts

@@ -427,6 +427,7 @@ import * as DesktopClientSettings from "../settings/DesktopClientSettings.ts";
 import * as DesktopWindow from "../window/DesktopWindow.ts";
 import * as DesktopSnapShot from "./DesktopSnapShot.ts";
 import * as SnapShotAccessibility from "./SnapShotAccessibility.ts";
+import { CaptureSetupRequiredError } from "./linuxCaptureSession.ts";
 
 const accessibilityApp = {
   byPid: accessibilityByPidMock,
@@ -1875,6 +1876,22 @@ it.effect("capture fails closed while snapshots are disabled", () => {
   ).pipe(Effect.provide(layerTest("win32")));
 });
 
+it.effect("points capture setup failures at SnapShot settings", () => {
+  vi.stubEnv("XDG_SESSION_TYPE", "wayland");
+  linuxCaptureMock.mockRejectedValueOnce(new CaptureSetupRequiredError("Install the helper."));
+  return Effect.scoped(
+    Effect.gen(function* () {
+      const service = yield* DesktopSnapShot.make;
+      yield* service.configure(enabledSettings());
+      const failure = yield* Effect.flip(service.capture);
+      assert.equal(failure.operation, "setup-required");
+    }),
+  ).pipe(
+    Effect.provide(layerTest("linux", { makeDirectory: () => Effect.void })),
+    Effect.ensuring(Effect.sync(() => vi.unstubAllEnvs())),
+  );
+});
+
 it.effect(
   "keeps saved preferences but rechecks access and shortcut delivery after changing desktops",
   () => {

apps/desktop/src/snapShot/DesktopSnapShot.ts

@@ -50,6 +50,7 @@ import { niriSocketPath } from "./NiriSnapShot.ts";
 import { CaptureShortcutConfig, niriCaptureConfigPath } from "./CaptureShortcutConfig.ts";
 import type { PortalCaptureShortcut } from "./PortalCaptureShortcut.ts";
 import {
+  CaptureSetupRequiredError,
   isGnomeCaptureSession,
   niriCaptureBinding,
   portalShortcutTrigger,
@@ -128,6 +129,7 @@ const DesktopSnapShotOperation = Schema.Literals([
   "disabled",
   "no-window-selected",
   "window-unavailable",
+  "setup-required",
   "capture",
 ]);
 
@@ -155,6 +157,8 @@ export class DesktopSnapShotError extends Schema.TaggedError<DesktopSnapShotErro
         return "No window was selected.";
       case "window-unavailable":
         return "The active window is not available for capture.";
+      case "setup-required":
+        return "Finish SnapShot setup in Settings → SnapShots.";
       case "capture":
         return "Could not capture the active window.";
     }
@@ -164,9 +168,9 @@ export class DesktopSnapShotError extends Schema.TaggedError<DesktopSnapShotErro
 const isDesktopSnapShotError = Schema.is(DesktopSnapShotError);
 
 function captureFailure(cause: unknown, captureId?: string): DesktopSnapShotError {
-  return isDesktopSnapShotError(cause)
-    ? cause
-    : new DesktopSnapShotError({ operation: "capture", captureId, cause });
+  if (isDesktopSnapShotError(cause)) return cause;
+  const operation = cause instanceof CaptureSetupRequiredError ? "setup-required" : "capture";
+  return new DesktopSnapShotError({ operation, captureId, cause });
 }
 
 export class DesktopSnapShot extends Context.Service<

apps/desktop/src/snapShot/HyprlandSnapShot.test.ts

@@ -18,6 +18,7 @@ import {
   hyprlandCaptureExecutable,
   hyprlandCaptureShortcut,
 } from "./HyprlandSnapShot.ts";
+import { CaptureSetupRequiredError } from "./linuxCaptureSession.ts";
 
 let directory: string;
 let paths: { bundle: string; dataHome: string };
@@ -86,6 +87,20 @@ it("updates explicitly and removes only its helper", async () => {
   expect((await setup.state()).status).toBe("not-installed");
   expect(await NodeFSP.readFile(unrelated, "utf8")).toBe("keep");
 });
+it("updates a helper left stale by an app update before capturing", async () => {
+  await setup.perform("install-hyprland-helper");
+  await NodeFSP.writeFile(paths.bundle, "update");
+  const result = await captureHyprlandWindow(paths);
+  expect(result.png).toEqual(png);
+  expect(await NodeFSP.readFile(hyprlandCaptureExecutable(paths), "utf8")).toBe("update");
+  result.feedback?.close();
+});
+it("leaves first-time installation to explicit setup", async () => {
+  await expect(captureHyprlandWindow(paths)).rejects.toBeInstanceOf(CaptureSetupRequiredError);
+  await expect(NodeFSP.stat(hyprlandCaptureExecutable(paths))).rejects.toMatchObject({
+    code: "ENOENT",
+  });
+});
 it("does not overwrite a linked executable", async () => {
   const executable = hyprlandCaptureExecutable(paths);
   await NodeFSP.mkdir(NodePath.dirname(executable), { recursive: true });

apps/desktop/src/snapShot/HyprlandSnapShot.ts

@@ -7,7 +7,7 @@ import * as NodeURL from "node:url";
 import * as Schema from "effect/Schema";
 import type { DesktopCaptureHelperState } from "@t3tools/contracts";
 import type { LinuxWindowSnapshot } from "./LinuxSnapShot.ts";
-import { readPortalPng } from "./linuxCaptureSession.ts";
+import { CaptureSetupRequiredError, readPortalPng } from "./linuxCaptureSession.ts";
 import { startNativeCaptureFeedback } from "./NativeCaptureFeedback.ts";
 import { HYPRLAND_CAPTURE_ACTION } from "./linuxCaptureSession.ts";
 export { isHyprlandCaptureSession } from "./linuxCaptureSession.ts";
@@ -167,9 +167,15 @@ export async function captureHyprlandWindow(
   paths: HyprlandCapturePaths,
   options?: { readonly flash: boolean; readonly animate: boolean },
 ): Promise<LinuxWindowSnapshot> {
-  const state = await new HyprlandCaptureSetup(paths).state();
-  if (state.status !== "ready")
-    throw new Error(`${state.message} Open Settings → SnapShots to continue setup.`);
+  const setup = new HyprlandCaptureSetup(paths);
+  let state = await setup.state();
+  if (state.status === "update-required") {
+    await setup.perform("install-hyprland-helper").catch((cause: unknown) => {
+      throw new CaptureSetupRequiredError(state.message, { cause });
+    });
+    state = await setup.state();
+  }
+  if (state.status !== "ready") throw new CaptureSetupRequiredError(state.message);
   const executable = hyprlandCaptureExecutable(paths);
   const directory = await NodeFSP.mkdtemp(NodePath.join(NodeOS.tmpdir(), "t3-hyprland-capture-"));
   const cleanup = () => NodeFSP.rm(directory, { recursive: true, force: true });

apps/desktop/src/snapShot/KdeSnapShot.ts

@@ -10,7 +10,7 @@ import type { DesktopCaptureHelperState } from "@t3tools/contracts";
 
 import { escapeDesktopEntryExecArgument } from "../app/DesktopLinuxUrlHandler.ts";
 import type { LinuxWindowSnapshot } from "./LinuxSnapShot.ts";
-import { readPortalPng } from "./linuxCaptureSession.ts";
+import { CaptureSetupRequiredError, readPortalPng } from "./linuxCaptureSession.ts";
 import { startNativeCaptureFeedback } from "./NativeCaptureFeedback.ts";
 export { isKdeCaptureSession } from "./linuxCaptureSession.ts";
 
@@ -215,8 +215,7 @@ export async function captureKdeWindow(
   options?: { readonly flash: boolean; readonly animate: boolean },
 ): Promise<LinuxWindowSnapshot> {
   const state = await new KdeCaptureSetup(paths).state();
-  if (state.status !== "ready")
-    throw new Error(`${state.message} Open Settings → SnapShots to continue setup.`);
+  if (state.status !== "ready") throw new CaptureSetupRequiredError(state.message);
   const { executable } = kdeCapturePaths(paths);
   const directory = await NodeFSP.mkdtemp(NodePath.join(NodeOS.tmpdir(), "t3-kde-capture-"));
   let retained = false;

apps/desktop/src/snapShot/linuxCaptureSession.ts

@@ -7,6 +7,12 @@ import { nativeImage } from "electron";
 // Keep dbus-next out of desktop detection and PNG reads in the main process.
 
 export const HYPRLAND_CAPTURE_ACTION = "capture-window";
+
+export class CaptureSetupRequiredError extends Error {
+  constructor(state: string, options?: ErrorOptions) {
+    super(`${state} Open Settings → SnapShots to continue setup.`, options);
+  }
+}
 export const NIRI_CAPTURE_PATH = "/com/t3tools/SnapShot";
 export const NIRI_CAPTURE_INTERFACE = "com.t3tools.SnapShot";
 

apps/mobile/README.md

@@ -1,7 +1,7 @@
 # T3 Code Mobile
 
-> [!WARNING]
-> T3 Code Mobile is currently in development and is not distributed yet. If you want to try it out, you can build it from source.
+> [!NOTE]
+> To install the released app from the App Store or Google Play, see [Mobile app](../../docs/user/install.md#mobile-app). This guide covers building it from source.
 
 ## Quickstart
 

apps/mobile/src/features/files/ThreadFilesRouteScreen.tsx

@@ -68,6 +68,7 @@ import {
   isMarkdownPreviewFile,
   isSvgImagePreviewFile,
   isVideoPreviewFile,
+  needsWorkspaceFileContents,
 } from "./filePath";
 import { useWorkspaceFileAssetUrlState } from "./workspaceFileAssetUrl";
 
@@ -707,15 +708,12 @@ export function ThreadFileScreen(props: ThreadFileRouteScreenProps) {
   const handleRetryPreview = () => {
     void assetPreview.refresh().finally(() => setPreviewRevision((current) => current + 1));
   };
-  const needsFileContents =
-    !metadataPending &&
-    directoryPath === null &&
-    relativePath !== null &&
-    !isVideoFile &&
-    !isAudioFile &&
-    (resolvedActiveMode === "source" ||
-      isMarkdownPreviewFile(relativePath) ||
-      filePreviewDelimiter({ name: relativePath }) !== null);
+  // Metadata is needed only to distinguish directories; file contents can load concurrently.
+  const needsFileContents = needsWorkspaceFileContents({
+    relativePath,
+    metadataKind: metadata.data?.kind,
+    activeMode: resolvedActiveMode,
+  });
   const fileQuery = useEnvironmentQuery(
     canReadFiles &&
       environmentId !== null &&

apps/mobile/src/features/files/filePath.test.ts

@@ -2,6 +2,7 @@ import { describe, expect, it } from "vite-plus/test";
 
 import {
   fileRoutePathSegments,
+  needsWorkspaceFileContents,
   resolveFileLinkPath,
   resolveWorkspaceRelativeFilePath,
 } from "./filePath";
@@ -49,3 +50,11 @@ describe("resolveWorkspaceRelativeFilePath", () => {
     expect(resolveWorkspaceRelativeFilePath(null, "/repo/main.ts")).toBeNull();
   });
 });
+
+describe("needsWorkspaceFileContents", () => {
+  it("reads a text file while its metadata is still pending, but not a directory", () => {
+    const input = { relativePath: "package.json", activeMode: "source" } as const;
+    expect(needsWorkspaceFileContents({ ...input, metadataKind: undefined })).toBe(true);
+    expect(needsWorkspaceFileContents({ ...input, metadataKind: "directory" })).toBe(false);
+  });
+});

apps/mobile/src/features/files/filePath.ts

@@ -1,3 +1,5 @@
+import type { FilesystemEntryMetadata } from "@t3tools/contracts";
+import { filePreviewDelimiter } from "@t3tools/shared/delimitedPreview";
 import { joinPath, resolvePathLinkTarget } from "@t3tools/shared/fileLinks";
 import {
   isWorkspaceAudioPreviewPath,
@@ -109,6 +111,23 @@ export function isMarkdownPreviewFile(path: string): boolean {
   return /\.(?:md|mdx)$/i.test(path.split(/[?#]/, 1)[0] ?? "");
 }
 
+export function needsWorkspaceFileContents(input: {
+  readonly relativePath: string | null;
+  readonly metadataKind: FilesystemEntryMetadata["kind"] | undefined;
+  readonly activeMode: "preview" | "source";
+}): boolean {
+  const path = input.relativePath;
+  return (
+    input.metadataKind !== "directory" &&
+    path !== null &&
+    !isVideoPreviewFile(path) &&
+    !isAudioPreviewFile(path) &&
+    (input.activeMode === "source" ||
+      isMarkdownPreviewFile(path) ||
+      filePreviewDelimiter({ name: path }) !== null)
+  );
+}
+
 export function fileHeaderSubtitle(projectName: string, relativePath: string): string {
   const parentDir = relativePath.slice(
     0,

apps/mobile/src/features/keyboard/CommandPalette.tsx

@@ -8,7 +8,11 @@ import {
   type EnvironmentThreadSearchMatch,
   type ShownOrder,
 } from "@t3tools/client-runtime/state/thread-search";
-import { isListedThreadLineage, THREAD_JUMP_KEYBINDING_COMMANDS } from "@t3tools/contracts";
+import {
+  AuthOrchestrationOperateScope,
+  isListedThreadLineage,
+  THREAD_JUMP_KEYBINDING_COMMANDS,
+} from "@t3tools/contracts";
 import {
   foldSearchQuery,
   PALETTE_MESSAGE_LIMIT,
@@ -53,6 +57,8 @@ import { requestThreadMessageJump } from "../threads/threadMessageJump";
 import { threadEnvironment } from "../../state/threads";
 import { useAtomCommand } from "../../state/use-atom-command";
 import { serverEnvironment } from "../../state/server";
+import { runPluginAction, usePluginActions } from "../../state/plugin-actions";
+import { useEnvironmentScope } from "../../state/session";
 import { useWorkspaceEnvironments } from "../../state/workspace";
 import { useSavedRemoteConnections } from "../../state/use-remote-environment-registry";
 import { useAppearancePreferences } from "../settings/appearance/AppearancePreferencesProvider";
@@ -62,6 +68,7 @@ import { useStartTriage } from "../triage/useStartTriage";
 import { useNewTaskFlow } from "../threads/new-task-flow-provider";
 import { useActiveNewTask } from "../../state/active-new-task";
 import {
+  buildPluginActionPaletteItems,
   filterCommandPaletteItems,
   nextPaletteIndex,
   type CommandPaletteItem,
@@ -102,6 +109,7 @@ const ACTION_ICONS: Record<string, AppSymbolName> = {
 
 function itemIcon(item: CommandPaletteItem): AppSymbolName {
   if (item.kind === "thread") return "text.bubble";
+  if (item.key.startsWith("plugin-action:")) return "cube";
   return ACTION_ICONS[item.key] ?? "ellipsis";
 }
 
@@ -231,6 +239,17 @@ export function CommandPalette(props: {
   const activeThread = useThreadShell(activeThreadRef);
   const visitThread = useAtomCommand(threadEnvironment.visit, { reportFailure: false });
   const environments = useWorkspaceEnvironments();
+  // Plugin actions belong to the open thread's environment, else the first connected one.
+  const pluginActionEnvironmentId =
+    activeThreadRef?.environmentId ??
+    environments.find((environment) => environment.connectionState === "connected")
+      ?.environmentId ??
+    null;
+  const pluginActions = usePluginActions(pluginActionEnvironmentId);
+  const canRunPluginActions = useEnvironmentScope(
+    pluginActionEnvironmentId,
+    AuthOrchestrationOperateScope,
+  );
   const { savedConnectionsById } = useSavedRemoteConnections();
   const [query, setQuery] = useState("");
   // Ranking is relative to when the palette opened, so rows do not reorder as time passes.
@@ -401,6 +420,18 @@ export function CommandPalette(props: {
         })),
       );
     }
+    if (pluginActionEnvironmentId !== null) {
+      actions.push(
+        ...buildPluginActionPaletteItems({
+          actions: pluginActions,
+          canOperate: canRunPluginActions,
+          environmentId: pluginActionEnvironmentId,
+          threadId: activeThread?.id ?? null,
+          projectId: activeThread?.projectId ?? null,
+          runAction: (input) => void runPluginAction(input),
+        }),
+      );
+    }
     const openProjects = projects.filter((project) => project.archivedAt == null);
     const projectItems: CommandPaletteItem[] = [
       ...openProjects.filter((project) => project.pinnedAt != null),
@@ -467,6 +498,9 @@ export function CommandPalette(props: {
     environments.length,
     canTriage,
     navigation,
+    canRunPluginActions,
+    pluginActionEnvironmentId,
+    pluginActions,
     projects,
     runCommand,
     savedConnectionsById,