Skip to content

The open-source app everyone uses to manage agents at work

Add instance heartbeat settings sidebar

Dotta32bdcf1dca5c
diff --git a/packages/shared/src/index.ts b/packages/shared/src/index.ts
index 67cf33f0ed..1a222f2778 100644
--- a/packages/shared/src/index.ts
+++ b/packages/shared/src/index.ts
@@ -99,6 +99,7 @@ export type {
AgentRuntimeState,
AgentTaskSession,
AgentWakeupRequest,
+ InstanceSchedulerHeartbeatAgent,
LiveEvent,
DashboardSummary,
ActivityEvent,
diff --git a/packages/shared/src/types/heartbeat.ts b/packages/shared/src/types/heartbeat.ts
index 7a1290e012..2e5a2006c5 100644
--- a/packages/shared/src/types/heartbeat.ts
+++ b/packages/shared/src/types/heartbeat.ts
@@ -1,4 +1,6 @@
import type {
+ AgentRole,
+ AgentStatus,
HeartbeatInvocationSource,
HeartbeatRunStatus,
WakeupTriggerDetail,
@@ -105,3 +107,20 @@ export interface AgentWakeupRequest {
createdAt: Date;
updatedAt: Date;
}
+
+export interface InstanceSchedulerHeartbeatAgent {
+ id: string;
+ companyId: string;
+ companyName: string;
+ companyIssuePrefix: string;
+ agentName: string;
+ agentUrlKey: string;
+ role: AgentRole;
+ title: string | null;
+ status: AgentStatus;
+ adapterType: string;
+ intervalSec: number;
+ heartbeatEnabled: boolean;
+ schedulerActive: boolean;
+ lastHeartbeatAt: Date | null;
+}
diff --git a/packages/shared/src/types/index.ts b/packages/shared/src/types/index.ts
index c01072d96e..07862c581e 100644
--- a/packages/shared/src/types/index.ts
+++ b/packages/shared/src/types/index.ts
@@ -48,6 +48,7 @@ export type {
AgentRuntimeState,
AgentTaskSession,
AgentWakeupRequest,
+ InstanceSchedulerHeartbeatAgent,
} from "./heartbeat.js";
export type { LiveEvent } from "./live.js";
export type { DashboardSummary } from "./dashboard.js";
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index d1dd1ddcfd..f6820f52ec 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -14,6 +14,9 @@ importers:
'@playwright/test':
specifier: ^1.58.2
version: 1.58.2
+ cross-env:
+ specifier: ^10.1.0
+ version: 10.1.0
esbuild:
specifier: ^0.27.3
version: 0.27.3
@@ -38,6 +41,9 @@ importers:
'@paperclipai/adapter-cursor-local':
specifier: workspace:*
version: link:../packages/adapters/cursor-local
+ '@paperclipai/adapter-gemini-local':
+ specifier: workspace:*
+ version: link:../packages/adapters/gemini-local
'@paperclipai/adapter-openclaw-gateway':
specifier: workspace:*
version: link:../packages/adapters/openclaw-gateway
@@ -68,6 +74,9 @@ importers:
drizzle-orm:
specifier: 0.38.4
+ embedded-postgres:
+ specifier: ^18.1.0-beta.16
+ version: 18.1.0-beta.16
picocolors:
specifier: ^1.1.1
version: 1.1.1
@@ -139,6 +148,22 @@ importers:
specifier: ^5.7.3
version: 5.9.3
+ packages/adapters/gemini-local:
+ dependencies:
+ '@paperclipai/adapter-utils':
+ specifier: workspace:*
+ version: link:../../adapter-utils
+ picocolors:
+ specifier: ^1.1.1
+ version: 1.1.1
+ devDependencies:
+ '@types/node':
+ specifier: ^24.6.0
+ version: 24.12.0
+ typescript:
+ specifier: ^5.7.3
+ version: 5.9.3
+
packages/adapters/openclaw-gateway:
dependencies:
'@paperclipai/adapter-utils':
@@ -245,6 +270,9 @@ importers:
'@paperclipai/adapter-cursor-local':
specifier: workspace:*
version: link:../packages/adapters/cursor-local
+ '@paperclipai/adapter-gemini-local':
+ specifier: workspace:*
+ version: link:../packages/adapters/gemini-local
'@paperclipai/adapter-openclaw-gateway':
specifier: workspace:*
version: link:../packages/adapters/openclaw-gateway
@@ -321,6 +349,9 @@ importers:
'@types/ws':
specifier: ^8.18.1
version: 8.18.1
+ cross-env:
+ specifier: ^10.1.0
+ version: 10.1.0
supertest:
specifier: ^7.0.0
version: 7.2.2
@@ -360,6 +391,9 @@ importers:
'@paperclipai/adapter-cursor-local':
specifier: workspace:*
version: link:../packages/adapters/cursor-local
+ '@paperclipai/adapter-gemini-local':
+ specifier: workspace:*
+ version: link:../packages/adapters/gemini-local
'@paperclipai/adapter-openclaw-gateway':
specifier: workspace:*
version: link:../packages/adapters/openclaw-gateway
@@ -989,6 +1023,9 @@ packages:
cpu: [x64]
os: [win32]
+ '@epic-web/[email protected]':
+ resolution: {integrity: sha512-lrTPqgvfFQtR/eY/qkIzp98OGdNJu0m5ji3q/nJI8v3SXkRKEnWiOxMmbvcSoAIzv/cGiuvRy57k4suKQSAdwA==}
+
'@esbuild-kit/[email protected]':
resolution: {integrity: sha512-sPRAnw9CdSsRmEtnsl2WXWdyquogVpB3yZ3dgwJfe8zrOzTsV7cJvmwrKVa+0ma5BoiGJ+BoqkMvawbayKUsqQ==}
deprecated: 'Merged into tsx: https://tsx.is'
@@ -3424,6 +3461,11 @@ packages:
resolution: {integrity: sha512-VQ2MBenTq1fWZUH9DJNGti7kKv6EeAuYr3cLwxUWhIu1baTaXh4Ib5W2CqHVqib4/MqbYGJqiL3Zb8GJZr3l4g==}
+ resolution: {integrity: sha512-GsYosgnACZTADcmEyJctkJIoqAhHjttw7RsFrVoJNXbsWWqaq6Ym+7kZjq6mS45O0jij6vtiReppKQEtqWy6Dw==}
+ engines: {node: '>=20'}
+ hasBin: true
+
resolution: {integrity: sha512-uV2QOWP2nWzsy2aMp8aRibhi9dlzF5Hgh5SHaB9OiTGEyDTiJJyx0uy51QXdyWbtAHNua4XJzUKca3OzKUd3vA==}
engines: {node: '>= 8'}
@@ -6741,6 +6783,8 @@ snapshots:
'@embedded-postgres/[email protected]':
optional: true
+ '@epic-web/[email protected]': {}
+
'@esbuild-kit/[email protected]':
dependencies:
esbuild: 0.18.20
@@ -9255,6 +9299,11 @@ snapshots:
+ dependencies:
+ '@epic-web/invariant': 1.0.0
+ cross-spawn: 7.0.6
+
dependencies:
path-key: 3.1.1
diff --git a/server/src/routes/agents.ts b/server/src/routes/agents.ts
index c4485d30cf..b1b5375918 100644
--- a/server/src/routes/agents.ts
+++ b/server/src/routes/agents.ts
@@ -8,9 +8,11 @@ import {
createAgentKeySchema,
createAgentHireSchema,
createAgentSchema,
+ deriveAgentUrlKey,
isUuidLike,
resetAgentSessionSchema,
testAdapterEnvironmentSchema,
+ type InstanceSchedulerHeartbeatAgent,
updateAgentPermissionsSchema,
updateAgentInstructionsPathSchema,
wakeAgentSchema,
@@ -202,6 +204,21 @@ export function agentRoutes(db: Db) {
return null;
}
+ function parseNumberLike(value: unknown): number | null {
+ if (typeof value === "number" && Number.isFinite(value)) return value;
+ if (typeof value !== "string") return null;
+ const parsed = Number(value.trim());
+ return Number.isFinite(parsed) ? parsed : null;
+ }
+
+ function parseSchedulerHeartbeatPolicy(runtimeConfig: unknown) {
+ const heartbeat = asRecord(asRecord(runtimeConfig)?.heartbeat) ?? {};
+ return {
+ enabled: parseBooleanLike(heartbeat.enabled) ?? true,
+ intervalSec: Math.max(0, parseNumberLike(heartbeat.intervalSec) ?? 0),
+ };
+ }
+
function generateEd25519PrivateKeyPem(): string {
const { privateKey } = generateKeyPairSync("ed25519");
return privateKey.export({ type: "pkcs8", format: "pem" }).toString();
@@ -454,6 +471,81 @@ export function agentRoutes(db: Db) {
res.json(result.map((agent) => redactForRestrictedAgentView(agent)));
});
+ router.get("/instance/scheduler-heartbeats", async (req, res) => {
+ assertBoard(req);
+
+ const accessConditions = [];
+ if (req.actor.source !== "local_implicit" && !req.actor.isInstanceAdmin) {
+ const allowedCompanyIds = req.actor.companyIds ?? [];
+ if (allowedCompanyIds.length === 0) {
+ res.json([]);
+ return;
+ }
+ accessConditions.push(inArray(agentsTable.companyId, allowedCompanyIds));
+ }
+
+ const rows = await db
+ .select({
+ id: agentsTable.id,
+ companyId: agentsTable.companyId,
+ agentName: agentsTable.name,
+ role: agentsTable.role,
+ title: agentsTable.title,
+ status: agentsTable.status,
+ adapterType: agentsTable.adapterType,
+ runtimeConfig: agentsTable.runtimeConfig,
+ lastHeartbeatAt: agentsTable.lastHeartbeatAt,
+ companyName: companies.name,
+ companyIssuePrefix: companies.issuePrefix,
+ })
+ .from(agentsTable)
+ .innerJoin(companies, eq(agentsTable.companyId, companies.id))
+ .where(accessConditions.length > 0 ? and(...accessConditions) : undefined)
+ .orderBy(companies.name, agentsTable.name);
+
+ const items: InstanceSchedulerHeartbeatAgent[] = rows
+ .map((row) => {
+ const policy = parseSchedulerHeartbeatPolicy(row.runtimeConfig);
+ const statusEligible =
+ row.status !== "paused" &&
+ row.status !== "terminated" &&
+ row.status !== "pending_approval";
+
+ return {
+ id: row.id,
+ companyId: row.companyId,
+ companyName: row.companyName,
+ companyIssuePrefix: row.companyIssuePrefix,
+ agentName: row.agentName,
+ agentUrlKey: deriveAgentUrlKey(row.agentName, row.id),
+ role: row.role as InstanceSchedulerHeartbeatAgent["role"],
+ title: row.title,
+ status: row.status as InstanceSchedulerHeartbeatAgent["status"],
+ adapterType: row.adapterType,
+ intervalSec: policy.intervalSec,
+ heartbeatEnabled: policy.enabled,
+ schedulerActive: statusEligible && policy.enabled && policy.intervalSec > 0,
+ lastHeartbeatAt: row.lastHeartbeatAt,
+ };
+ })
+ .filter((item) =>
+ item.intervalSec > 0 &&
+ item.status !== "paused" &&
+ item.status !== "terminated" &&
+ item.status !== "pending_approval",
+ )
+ .sort((left, right) => {
+ if (left.schedulerActive !== right.schedulerActive) {
+ return left.schedulerActive ? -1 : 1;
+ }
+ const companyOrder = left.companyName.localeCompare(right.companyName);
+ if (companyOrder !== 0) return companyOrder;
+ return left.agentName.localeCompare(right.agentName);
+ });
+
+ res.json(items);
+ });
+
router.get("/companies/:companyId/org", async (req, res) => {
const companyId = req.params.companyId as string;
assertCompanyAccess(req, companyId);
diff --git a/ui/src/App.tsx b/ui/src/App.tsx
index a3e35de167..ed6c9c5170 100644
--- a/ui/src/App.tsx
+++ b/ui/src/App.tsx
@@ -23,6 +23,7 @@ import { Activity } from "./pages/Activity";
import { Inbox } from "./pages/Inbox";
import { CompanySettings } from "./pages/CompanySettings";
import { DesignGuide } from "./pages/DesignGuide";
+import { InstanceSettings } from "./pages/InstanceSettings";
import { RunTranscriptUxLab } from "./pages/RunTranscriptUxLab";
import { OrgChart } from "./pages/OrgChart";
import { NewAgent } from "./pages/NewAgent";
@@ -109,6 +110,8 @@ function boardRoutes() {
<Route path="dashboard" element={<Dashboard />} />
<Route path="companies" element={<Companies />} />
<Route path="company/settings" element={<CompanySettings />} />
+ <Route path="settings" element={<LegacySettingsRedirect />} />
+ <Route path="settings/*" element={<LegacySettingsRedirect />} />
<Route path="org" element={<OrgChart />} />
<Route path="agents" element={<Navigate to="/agents/all" replace />} />
<Route path="agents/all" element={<Agents />} />
@@ -156,6 +159,11 @@ function InboxRootRedirect() {
return <Navigate to={`/inbox/${loadLastInboxTab()}`} replace />;
}
+function LegacySettingsRedirect() {
+ const location = useLocation();
+ return <Navigate to={`/instance/settings${location.search}${location.hash}`} replace />;
+}
+
function CompanyRootRedirect() {
const { companies, selectedCompany, loading } = useCompany();
const { onboardingOpen } = useDialog();
@@ -234,9 +242,15 @@ export function App() {
<Route element={<CloudAccessGate />}>
<Route index element={<CompanyRootRedirect />} />
+ <Route path="instance" element={<Navigate to="/instance/settings" replace />} />
+ <Route path="instance/settings" element={<Layout />}>
+ <Route index element={<InstanceSettings />} />
+ </Route>
<Route path="companies" element={<UnprefixedBoardRedirect />} />
<Route path="issues" element={<UnprefixedBoardRedirect />} />
<Route path="issues/:issueId" element={<UnprefixedBoardRedirect />} />
+ <Route path="settings" element={<LegacySettingsRedirect />} />
+ <Route path="settings/*" element={<LegacySettingsRedirect />} />
<Route path="agents" element={<UnprefixedBoardRedirect />} />
<Route path="agents/new" element={<UnprefixedBoardRedirect />} />
<Route path="agents/:agentId" element={<UnprefixedBoardRedirect />} />
diff --git a/ui/src/api/heartbeats.ts b/ui/src/api/heartbeats.ts
index b579a65d1b..9b8a714546 100644
--- a/ui/src/api/heartbeats.ts
+++ b/ui/src/api/heartbeats.ts
@@ -1,4 +1,8 @@
-import type { HeartbeatRun, HeartbeatRunEvent } from "@paperclipai/shared";
+import type {
+ HeartbeatRun,
+ HeartbeatRunEvent,
+ InstanceSchedulerHeartbeatAgent,
+} from "@paperclipai/shared";
import { api } from "./client";
export interface ActiveRunForIssue extends HeartbeatRun {
@@ -45,4 +49,6 @@ export const heartbeatsApi = {
api.get<ActiveRunForIssue | null>(`/issues/${issueId}/active-run`),
liveRunsForCompany: (companyId: string, minCount?: number) =>
api.get<LiveRunForIssue[]>(`/companies/${companyId}/live-runs${minCount ? `?minCount=${minCount}` : ""}`),
+ listInstanceSchedulerAgents: () =>
+ api.get<InstanceSchedulerHeartbeatAgent[]>("/instance/scheduler-heartbeats"),
};
diff --git a/ui/src/components/CompanyRail.tsx b/ui/src/components/CompanyRail.tsx
index 4737d0479c..fa981d1bad 100644
--- a/ui/src/components/CompanyRail.tsx
+++ b/ui/src/components/CompanyRail.tsx
@@ -22,6 +22,7 @@ import { cn } from "../lib/utils";
import { queryKeys } from "../lib/queryKeys";
import { sidebarBadgesApi } from "../api/sidebarBadges";
import { heartbeatsApi } from "../api/heartbeats";
+import { useLocation, useNavigate } from "@/lib/router";
import {
Tooltip,
TooltipContent,
@@ -154,6 +155,10 @@ function SortableCompanyItem({
export function CompanyRail() {
const { companies, selectedCompanyId, setSelectedCompanyId } = useCompany();
const { openOnboarding } = useDialog();
+ const navigate = useNavigate();
+ const location = useLocation();
+ const isInstanceRoute = location.pathname.startsWith("/instance/");
+ const highlightedCompanyId = isInstanceRoute ? null : selectedCompanyId;
const sidebarCompanies = useMemo(
() => companies.filter((company) => company.status !== "archived"),
[companies],
@@ -282,10 +287,15 @@ export function CompanyRail() {
<SortableCompanyItem
key={company.id}
company={company}
- isSelected={company.id === selectedCompanyId}
+ isSelected={company.id === highlightedCompanyId}
hasLiveAgents={hasLiveAgentsByCompanyId.get(company.id) ?? false}
hasUnreadInbox={hasUnreadInboxByCompanyId.get(company.id) ?? false}
- onSelect={() => setSelectedCompanyId(company.id)}
+ onSelect={() => {
+ setSelectedCompanyId(company.id);
+ if (isInstanceRoute) {
+ navigate(`/${company.issuePrefix}/dashboard`);
+ }
+ }}
/>
))}
</SortableContext>
diff --git a/ui/src/components/InstanceSidebar.tsx b/ui/src/components/InstanceSidebar.tsx
new file mode 100644
index 0000000000..ac933aa1d0
--- /dev/null
+++ b/ui/src/components/InstanceSidebar.tsx
@@ -0,0 +1,21 @@
+import { Clock3, Settings } from "lucide-react";
+import { SidebarNavItem } from "./SidebarNavItem";
+
+export function InstanceSidebar() {
+ return (
+ <aside className="w-60 h-full min-h-0 border-r border-border bg-background flex flex-col">
+ <div className="flex items-center gap-2 px-3 h-12 shrink-0">
+ <Settings className="h-4 w-4 text-muted-foreground shrink-0 ml-1" />
+ <span className="flex-1 text-sm font-bold text-foreground truncate">
+ Instance Settings
+ </span>
+ </div>
+
+ <nav className="flex-1 min-h-0 overflow-y-auto scrollbar-auto-hide flex flex-col gap-4 px-3 py-2">
+ <div className="flex flex-col gap-0.5">
+ <SidebarNavItem to="/instance/settings" label="Heartbeats" icon={Clock3} />
+ </div>
+ </nav>
+ </aside>
+ );
+}
diff --git a/ui/src/components/Layout.tsx b/ui/src/components/Layout.tsx
index e12e6717b7..12cc6f8867 100644
--- a/ui/src/components/Layout.tsx
+++ b/ui/src/components/Layout.tsx
@@ -1,9 +1,10 @@
import { useCallback, useEffect, useMemo, useRef, useState } from "react";
import { useQuery } from "@tanstack/react-query";
-import { BookOpen, Moon, Sun } from "lucide-react";
-import { Outlet, useLocation, useNavigate, useParams } from "@/lib/router";
+import { BookOpen, Moon, Settings, Sun } from "lucide-react";
+import { Link, Outlet, useLocation, useNavigate, useParams } from "@/lib/router";
import { CompanyRail } from "./CompanyRail";
import { Sidebar } from "./Sidebar";
+import { InstanceSidebar } from "./InstanceSidebar";
import { SidebarNavItem } from "./SidebarNavItem";
import { BreadcrumbBar } from "./BreadcrumbBar";
import { PropertiesPanel } from "./PropertiesPanel";
@@ -42,6 +43,7 @@ export function Layout() {
const { companyPrefix } = useParams<{ companyPrefix: string }>();
const navigate = useNavigate();
const location = useLocation();
+ const isInstanceSettingsRoute = location.pathname.startsWith("/instance/");
const onboardingTriggered = useRef(false);
const lastMainScrollTop = useRef(0);
const [mobileNavVisible, setMobileNavVisible] = useState(true);
@@ -242,7 +244,7 @@ export function Layout() {
>
<div className="flex flex-1 min-h-0 overflow-hidden">
<CompanyRail />
- <Sidebar />
+ {isInstanceSettingsRoute ? <InstanceSidebar /> : <Sidebar />}
</div>
<div className="border-t border-r border-border px-3 py-2 bg-background">
<div className="flex items-center gap-1">
@@ -252,6 +254,18 @@ export function Layout() {
icon={BookOpen}
className="flex-1 min-w-0"
/>
+ <Button variant="ghost" size="icon-sm" className="text-muted-foreground shrink-0" asChild>
+ <Link
+ to="/instance/settings"
+ aria-label="Instance settings"
+ title="Instance settings"
+ onClick={() => {
+ if (isMobile) setSidebarOpen(false);
+ }}
+ >
+ <Settings className="h-4 w-4" />
+ </Link>
+ </Button>
<Button
type="button"
variant="ghost"
@@ -276,7 +290,7 @@ export function Layout() {
sidebarOpen ? "w-60" : "w-0"
)}
>
- <Sidebar />
+ {isInstanceSettingsRoute ? <InstanceSidebar /> : <Sidebar />}
</div>
</div>
<div className="border-t border-r border-border px-3 py-2">
@@ -287,6 +301,18 @@ export function Layout() {
icon={BookOpen}
className="flex-1 min-w-0"
/>
+ <Button variant="ghost" size="icon-sm" className="text-muted-foreground shrink-0" asChild>
+ <Link
+ to="/instance/settings"
+ aria-label="Instance settings"
+ title="Instance settings"
+ onClick={() => {
+ if (isMobile) setSidebarOpen(false);
+ }}
+ >
+ <Settings className="h-4 w-4" />
+ </Link>
+ </Button>
<Button
type="button"
variant="ghost"
diff --git a/ui/src/lib/company-routes.ts b/ui/src/lib/company-routes.ts
index ac8c3f7e4c..736e38970a 100644
--- a/ui/src/lib/company-routes.ts
+++ b/ui/src/lib/company-routes.ts
@@ -14,7 +14,7 @@ const BOARD_ROUTE_ROOTS = new Set([
"design-guide",
]);
-const GLOBAL_ROUTE_ROOTS = new Set(["auth", "invite", "board-claim", "docs"]);
+const GLOBAL_ROUTE_ROOTS = new Set(["auth", "invite", "board-claim", "docs", "instance"]);
export function normalizeCompanyPrefix(prefix: string): string {
return prefix.trim().toUpperCase();
diff --git a/ui/src/lib/queryKeys.ts b/ui/src/lib/queryKeys.ts
index ff73701f41..c500afdc5f 100644
--- a/ui/src/lib/queryKeys.ts
+++ b/ui/src/lib/queryKeys.ts
@@ -56,6 +56,9 @@ export const queryKeys = {
auth: {
session: ["auth", "session"] as const,
},
+ instance: {
+ schedulerHeartbeats: ["instance", "scheduler-heartbeats"] as const,
+ },
health: ["health"] as const,
secrets: {
list: (companyId: string) => ["secrets", companyId] as const,