feat: Hermes gateway provider — agent instances, Home threads, and first-class agent UX

.github/workflows/ci.yml

@@ -99,3 +99,22 @@ jobs:
 
       - name: Exercise release-only workflow steps
         run: node scripts/release-smoke.ts
+
+  hermes_plugin:
+    name: Hermes Plugin
+    runs-on: blacksmith-8vcpu-ubuntu-2404
+    timeout-minutes: 5
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Lint
+        run: pipx run ruff check integrations/hermes-t3-gateway
+
+      - name: Test
+        run: python -m unittest discover -s integrations/hermes-t3-gateway/tests -v

.gitignore

@@ -35,3 +35,5 @@ node_modules/
 *.log
 .env*
 !.env.example
+__pycache__/
+*.py[cod]

apps/mobile/src/features/archive/archivedThreadList.test.ts

@@ -13,6 +13,7 @@ function makeProject(
   return {
     workspaceRoot: `/workspaces/${input.id}`,
     repositoryIdentity: null,
+    agentInstanceId: null,
     defaultModelSelection: null,
     scripts: [],
     createdAt: "2026-06-01T00:00:00.000Z",

apps/mobile/src/features/home/HomeRouteScreen.tsx

@@ -3,6 +3,7 @@ import * as Order from "effect/Order";
 import { useNavigation } from "@react-navigation/native";
 import { useEffect, useMemo, useState } from "react";
 
+import { selectWorkspaceProjects } from "../../lib/repositoryGroups";
 import { NativeHeaderToolbar, NativeStackScreenOptions } from "../../native/StackHeader";
 import { useProjects, useThreadShells } from "../../state/entities";
 import { usePendingNewTasks } from "../../state/use-pending-new-tasks";
@@ -59,10 +60,12 @@ export function HomeRouteScreen() {
   } = useHomeListOptions(availableEnvironmentIds);
   const selectedEnvironmentId = listOptions.selectedEnvironmentId;
   const [selectedProjectKey, setSelectedProjectKey] = useState<string | null>(null);
+  // Filter menu = picker: agent projects are excluded here, while the thread
+  // list below still receives the full list so agent threads stay visible.
   const projectFilterOptions = useMemo(
     () =>
       buildHomeProjectScopes({
-        projects,
+        projects: selectWorkspaceProjects(projects),
         environmentId: selectedEnvironmentId,
         projectGroupingMode: listOptions.projectGroupingMode,
       }).map((scope) => ({

apps/mobile/src/features/home/HomeScreen.tsx

@@ -24,6 +24,7 @@ import { AppText as Text } from "../../components/AppText";
 import { EmptyState } from "../../components/EmptyState";
 import type { WorkspaceState } from "../../state/workspaceModel";
 import type { SavedRemoteConnection } from "../../lib/connection";
+import { selectWorkspaceProjects } from "../../lib/repositoryGroups";
 import { scopedProjectKey } from "../../lib/scopedEntities";
 import { NATIVE_LIQUID_GLASS_SUPPORTED } from "../../native/native-glass";
 import { mobilePreferencesAtom, updateMobilePreferencesAtom } from "../../state/preferences";
@@ -773,7 +774,9 @@ export function HomeScreen(props: HomeScreenProps) {
   const shouldShowConnectionStatus = shouldShowWorkspaceConnectionStatus(props.catalogState);
   const emptyState = deriveEmptyState({
     catalogState: props.catalogState,
-    projectCount: props.projects.length,
+    // "No projects found" counts real workspaces: a synthetic agent project
+    // is not something the user added, so it must not suppress the hint.
+    projectCount: selectWorkspaceProjects(props.projects).length,
   });
   const connectionStatus =
     shouldShowConnectionStatus && Platform.OS !== "ios" ? (

apps/mobile/src/features/home/homeListItems.test.ts

@@ -25,6 +25,7 @@ function makeProject(id: string, title: string): EnvironmentProject {
     title,
     workspaceRoot: `/workspaces/${id}`,
     repositoryIdentity: null,
+    agentInstanceId: null,
     defaultModelSelection: null,
     scripts: [],
     createdAt: "2026-06-01T00:00:00.000Z",

apps/mobile/src/features/home/homeThreadList.test.ts

@@ -17,6 +17,7 @@ function makeProject(
   return {
     workspaceRoot: `/workspaces/${input.id}`,
     repositoryIdentity: null,
+    agentInstanceId: null,
     defaultModelSelection: null,
     scripts: [],
     createdAt: "2026-06-01T00:00:00.000Z",

apps/mobile/src/features/home/homeThreadList.ts

@@ -56,6 +56,11 @@ export function buildHomeProjectScopes(input: {
   readonly environmentId: EnvironmentId | null;
   readonly projectGroupingMode: SidebarProjectGroupingMode;
 }): ReadonlyArray<HomeProjectScope> {
+  // NOTE: agent projects are deliberately *not* filtered here. This builder
+  // feeds both the project filter menu (a picker — callers pass an
+  // agent-free list, see `selectWorkspaceProjects`) and the thread list
+  // itself. Excluding agent projects here would silently drop every agent
+  // thread from mobile, which has no Agents surface to show them in instead.
   const projects = input.projects.filter(
     (project) => input.environmentId === null || project.environmentId === input.environmentId,
   );
@@ -305,6 +310,9 @@ export function buildHomeThreadGroups(input: {
             workspaceRoot:
               pendingTask.creation.projectCwd ?? String(pendingTask.creation.projectId),
             repositoryIdentity: null,
+            // A queued task always targets a real workspace; agent projects
+            // never enqueue through this path.
+            agentInstanceId: null,
             defaultModelSelection: null,
             scripts: [],
             createdAt: pendingTask.message.createdAt,

apps/mobile/src/features/projects/AddProjectScreen.tsx

@@ -32,6 +32,7 @@ import * as Cause from "effect/Cause";
 import * as Order from "effect/Order";
 import { AsyncResult } from "effect/unstable/reactivity";
 import { cn } from "../../lib/cn";
+import { selectWorkspaceProjects } from "../../lib/repositoryGroups";
 
 import { useProjects, useServerConfigs } from "../../state/entities";
 import { filesystemEnvironment } from "../../state/filesystem";
@@ -496,7 +497,9 @@ export function AddProjectSourceScreen() {
 function useCreateProject(environment: EnvironmentOption | null) {
   const navigation = useNavigation();
   const createProject = useAtomCommand(projectEnvironment.create, { reportFailure: false });
-  const projects = useProjects();
+  // Dedupe against real projects only: an agent's synthetic directory should
+  // never make "add project" bounce the user into an agent thread.
+  const projects = selectWorkspaceProjects(useProjects());
 
   return useCallback(
     async (workspaceRoot: string) => {

apps/mobile/src/features/showcase/showcasePendingTasks.test.ts

@@ -14,6 +14,7 @@ const projects: ReadonlyArray<EnvironmentProject> = [
     title: "T3 Code",
     workspaceRoot: "/workspace/t3code",
     repositoryIdentity: null,
+    agentInstanceId: null,
     defaultModelSelection: { instanceId: ProviderInstanceId.make("codex"), model: "gpt-5.4" },
     scripts: [],
     createdAt: "2026-07-16T08:00:00.000Z",
@@ -25,6 +26,7 @@ const projects: ReadonlyArray<EnvironmentProject> = [
     title: "React",
     workspaceRoot: "/workspace/react",
     repositoryIdentity: null,
+    agentInstanceId: null,
     defaultModelSelection: null,
     scripts: [],
     createdAt: "2026-07-16T08:00:00.000Z",

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

@@ -44,6 +44,7 @@ import {
 } from "../../state/use-composer-drafts";
 import { useProjects } from "../../state/entities";
 import { deriveThreadTitleFromPrompt } from "../../lib/projectThreadStartTurn";
+import { selectWorkspaceProjects } from "../../lib/repositoryGroups";
 import { armAgentAwarenessLiveActivityForLocalWork } from "../agent-awareness/remoteRegistration";
 import { enqueueThreadOutboxMessage, removeThreadOutboxMessage } from "../../state/thread-outbox";
 import { useRemoteConnectionStatus } from "../../state/use-remote-environment-registry";
@@ -73,7 +74,12 @@ export function NewTaskDraftScreen(props: {
   /** Durable native share inbox item to merge into this project draft. */
   readonly incomingShareId?: string;
 }) {
-  const projects = useProjects();
+  // Filtered wholesale: mobile has no agent surface, so a route (or share
+  // reservation) pointing at a synthetic agent project should fall through to
+  // "return to the project picker" rather than open a draft against an empty
+  // agent directory.
+  const allProjects = useProjects();
+  const projects = useMemo(() => selectWorkspaceProjects(allProjects), [allProjects]);
   const createProjectThread = useCreateProjectThread();
   const flow = useNewTaskFlow();
   const navigation = useNavigation();
@@ -264,7 +270,12 @@ export function NewTaskDraftScreen(props: {
         return;
       }
 
-      if (projects.length > 0) {
+      // Guard on the *unfiltered* catalog. `projects` drops synthetic agent
+      // projects, so an agent-only environment is indistinguishable from a
+      // catalog that has not loaded yet — and a route pointing at an agent
+      // project then found no directProject, skipped this branch, and left the
+      // screen on "Loading task" with nothing left to resolve it.
+      if (allProjects.length > 0) {
         // Never fall through to the flow provider's temporary first-project
         // default. Return to the picker with the share id intact so the user
         // can choose an available destination.
@@ -284,6 +295,7 @@ export function NewTaskDraftScreen(props: {
 
     navigation.dispatch(StackActions.replace("NewTask"));
   }, [
+    allProjects,
     logicalProjects,
     projects,
     props.initialProjectRef,

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

@@ -21,6 +21,7 @@ import { ControlPillMenu } from "../../components/ControlPill";
 import { SymbolView } from "../../components/AppSymbol";
 import { NATIVE_LIQUID_GLASS_SUPPORTED } from "../../native/native-glass";
 import { NativeStackScreenOptions } from "../../native/StackHeader";
+import { selectWorkspaceProjects } from "../../lib/repositoryGroups";
 import { scopedProjectKey, scopedThreadKey } from "../../lib/scopedEntities";
 import { useThemeColor } from "../../lib/useThemeColor";
 import { useProjects, useThreadShells } from "../../state/entities";
@@ -219,13 +220,19 @@ function ThreadNavigationSidebarPane(
       }),
     [options.projectGroupingMode, options.selectedEnvironmentId, projects],
   );
+  // The scope list above stays complete so agent threads remain visible and
+  // scopable; only the *picker* built from it drops agent projects.
   const projectFilterOptions = useMemo(
     () =>
-      projectScopes.map((scope) => ({
+      buildHomeProjectScopes({
+        projects: selectWorkspaceProjects(projects),
+        environmentId: options.selectedEnvironmentId,
+        projectGroupingMode: options.projectGroupingMode,
+      }).map((scope) => ({
         key: scope.key,
         label: scope.title,
       })),
-    [projectScopes],
+    [options.projectGroupingMode, options.selectedEnvironmentId, projects],
   );
   const projectTitleByProjectKey = useMemo(
     () =>

apps/mobile/src/features/threads/new-task-flow-provider.tsx

@@ -23,7 +23,7 @@ import type { TurnCommandMetadata } from "../../lib/commandMetadata";
 import type { DraftComposerImageAttachment } from "../../lib/composerImages";
 import type { ModelOption, ProviderGroup } from "../../lib/modelOptions";
 import { buildModelOptions, groupByProvider } from "../../lib/modelOptions";
-import { groupProjectsByRepository } from "../../lib/repositoryGroups";
+import { groupProjectsByRepository, selectWorkspaceProjects } from "../../lib/repositoryGroups";
 import { scopedProjectKey } from "../../lib/scopedEntities";
 import { appAtomRegistry } from "../../state/atom-registry";
 import {
@@ -168,7 +168,12 @@ type NewTaskFlowContextValue = {
 const NewTaskFlowContext = React.createContext<NewTaskFlowContextValue | null>(null);
 
 export function NewTaskFlowProvider(props: React.PropsWithChildren) {
-  const projects = useProjects();
+  // Every use of this list is part of choosing a destination for a new task,
+  // so synthetic agent projects are excluded once, here, rather than at each
+  // of the environment/project selection sites below. Memoized because the
+  // downstream grouping/selection memos take it as a dependency.
+  const allProjects = useProjects();
+  const projects = useMemo(() => selectWorkspaceProjects(allProjects), [allProjects]);
   const threads = useThreadShells();
   const { savedConnectionsById } = useSavedRemoteConnections();
 
@@ -259,6 +264,9 @@ export function NewTaskFlowProvider(props: React.PropsWithChildren) {
       // fabricated path.
       workspaceRoot: creation.projectCwd ?? "",
       repositoryIdentity: null,
+      // A queued task always targets a real workspace; agent projects never
+      // enqueue through this path.
+      agentInstanceId: null,
       defaultModelSelection: editingPendingTask.modelSelection ?? null,
       scripts: [],
       createdAt: editingPendingTask.createdAt,

apps/mobile/src/lib/repositoryGroups.test.ts

@@ -2,7 +2,7 @@ import { describe, expect, it } from "vite-plus/test";
 
 import { EnvironmentId, ProjectId, ProviderInstanceId, ThreadId } from "@t3tools/contracts";
 
-import { groupProjectsByRepository } from "./repositoryGroups";
+import { groupProjectsByRepository, isAgentProject } from "./repositoryGroups";
 import { EnvironmentProject, EnvironmentThreadShell } from "@t3tools/client-runtime/state/shell";
 
 function makeProject(
@@ -11,6 +11,7 @@ function makeProject(
   return {
     workspaceRoot: `/workspaces/${input.id}`,
     repositoryIdentity: null,
+    agentInstanceId: null,
     defaultModelSelection: null,
     scripts: [],
     createdAt: "2026-04-01T00:00:00.000Z",
@@ -190,3 +191,50 @@ describe("groupProjectsByRepository", () => {
     expect(groups[0]?.subtitle).toBeNull();
   });
 });
+
+describe("agent project exclusion", () => {
+  const environmentId = EnvironmentId.make("env-local");
+  const agentInstanceId = ProviderInstanceId.make("hermes_workstation");
+
+  it("keeps a project with no reported agent instance", () => {
+    // Older snapshots omit `agentInstanceId` entirely; that must read as an
+    // ordinary project, not as an agent.
+    expect(
+      isAgentProject(
+        makeProject({ environmentId, id: ProjectId.make("project-legacy"), title: "Legacy" }),
+      ),
+    ).toBe(false);
+  });
+
+  it("identifies a synthetic agent project", () => {
+    expect(
+      isAgentProject(
+        makeProject({
+          environmentId,
+          id: ProjectId.make("project-agent"),
+          title: "Workstation",
+          agentInstanceId,
+        }),
+      ),
+    ).toBe(true);
+  });
+
+  it("omits agent projects from repository groups", () => {
+    const workspace = makeProject({
+      environmentId,
+      id: ProjectId.make("project-real"),
+      title: "Real",
+    });
+    const agent = makeProject({
+      environmentId,
+      id: ProjectId.make("project-agent"),
+      title: "Workstation",
+      agentInstanceId,
+    });
+
+    const groups = groupProjectsByRepository({ projects: [workspace, agent], threads: [] });
+
+    expect(groups).toHaveLength(1);
+    expect(groups[0]?.projects[0]?.project.id).toBe(workspace.id);
+  });
+});

apps/mobile/src/lib/repositoryGroups.ts

@@ -58,10 +58,34 @@ function deriveProjectLatestActivity(
   return latestThread?.updatedAt ?? latestThread?.createdAt ?? project.updatedAt;
 }
 
-export function groupProjectsByRepository(input: {
+/**
+ * True for the synthetic project row backing an agent instance
+ * (`OrchestrationProjectShell.agentInstanceId`). Such a row is a legal project
+ * with a real — but empty — workspace directory, created only so an agent
+ * thread can satisfy `project_id NOT NULL`. It is never a workspace the user
+ * chose, so it must not appear in any surface that offers a project to pick.
+ */
+export function isAgentProject(project: Pick<EnvironmentProject, "agentInstanceId">): boolean {
+  // `!= null` on purpose: the contract decodes a default of `null`, but an
+  // older snapshot (or a partial fixture) can omit the field entirely, and
+  // "not reported" must mean "ordinary project", never "agent".
+  return project.agentInstanceId != null;
+}
+
+/** Drop synthetic agent projects from a list destined for a picker. */
+export function selectWorkspaceProjects<
+  TProject extends Pick<EnvironmentProject, "agentInstanceId">,
+>(projects: ReadonlyArray<TProject>): TProject[] {
+  return projects.filter((project) => !isAgentProject(project));
+}
+
+export function groupProjectsByRepository(rawInput: {
   readonly projects: ReadonlyArray<EnvironmentProject>;
   readonly threads: ReadonlyArray<EnvironmentThreadShell>;
 }): ReadonlyArray<RepositoryGroup> {
+  // This grouping only ever feeds the "choose a project" screens, so the
+  // exclusion lives here rather than at each call site.
+  const input = { ...rawInput, projects: selectWorkspaceProjects(rawInput.projects) };
   const threadsByProjectKey = new Map<string, EnvironmentThreadShell[]>();
 
   for (const thread of input.threads) {

apps/mobile/src/widgets/AgentActivity.tsx

@@ -23,6 +23,7 @@ export type AgentActivityPhase =
   | "running"
   | "waiting_for_approval"
   | "waiting_for_input"
+  | "notification"
   | "completed"
   | "failed"
   | "stale";
@@ -81,6 +82,8 @@ export function AgentActivity(
         return isLightScheme ? "#d97706" : "#fcd34d"; // amber-600 / amber-300
       case "waiting_for_input":
         return isLightScheme ? "#4f46e5" : "#a5b4fc"; // indigo-600 / indigo-300
+      case "notification":
+        return isLightScheme ? "#7c3aed" : "#c4b5fd"; // violet-600 / violet-300
       case "failed":
         return isLightScheme ? "#dc2626" : "#fca5a5"; // red-600 / red-300
       case "completed":
@@ -97,7 +100,9 @@ export function AgentActivity(
   const phasePriority = (phase: AgentActivityPhase): number => {
     if (phase === "waiting_for_approval" || phase === "waiting_for_input") return 0;
     if (phase === "failed") return 1;
-    if (phase === "running" || phase === "starting") return 2;
+    // A proactive delivery is unread news, so it outranks finished/stale rows
+    // but never a human who is actually blocked.
+    if (phase === "running" || phase === "starting" || phase === "notification") return 2;
     return 3;
   };
   const ordered = [...props.activities].sort(
@@ -163,6 +168,8 @@ export function AgentActivity(
         return "exclamationmark.circle.fill";
       case "waiting_for_input":
         return "questionmark.circle.fill";
+      case "notification":
+        return "bell.badge.fill";
       case "failed":
         return "xmark.octagon.fill";
       case "completed":