Compare commits

..
Author SHA1 Message Date
Mohamed Boudra 36dbeb1943 docs(hub): clarify trigger authoring and event limits 2026-11-20 17:31:13 +01:00
Mohamed Boudra d6fa19f2d5 docs(hub): distinguish dashboard saves from trigger deploys 2026-11-20 17:18:00 +01:00
Mohamed Boudra 1d3e2e7804 docs(hub): clarify trigger validation and dispatch behavior 2026-11-20 17:07:06 +01:00
Mohamed Boudra 19a7c33881 docs(hub): address PR review findings and split dense paragraphs
Fixes all five accuracy findings across English and Simplified Chinese docs: Audience: Everyone default (from_users: ["*"]), queued dispatch retries for offline daemons, launch-time run.github.connection lookup, ${{ paseo.prompt }} in the manual-task API example, and the execution-mode requirement for paseo hub init. Splits all paragraphs and list items longer than three sentences across Hub docs and the Hub sections of CLI and security docs.
2026-11-20 17:04:31 +01:00
Mohamed Boudra afb78c5f8c docs(hub): rewrite Hub docs for triggers, Linear, webhooks, schedules, and scoped tools
Removes legacy multi-step workflow and hub.yml documentation and aligns all English and Simplified Chinese Hub guides with current Hub behavior: self-contained .paseo/triggers/*.yml documents, generic daemon providers, Integrations terminology, Linear app and triggers, scheduled triggers, inbound webhooks, scoped Slack and Discord MCP tools, and Open in Paseo reply links. Adds legacy doc redirects and per-source trigger doc links in the /hub showcase.
2026-11-20 17:04:30 +01:00
Mohamed Boudra 6be18380d7 fix(website): let Hub source descriptions wrap 2026-11-20 16:35:04 +01:00
Mohamed Boudra 3eb22ce65d fix(website): keep the Discord preview thread title readable 2026-11-20 16:27:47 +01:00
Mohamed Boudra 37b138b126 fix(website): wrap result chips in the Hub schedule preview 2026-11-20 16:17:37 +01:00
Mohamed Boudra d1a38073e3 fix(website): wrap long identifiers in Hub previews 2026-11-20 16:15:07 +01:00
Mohamed Boudra 4d7b578bbd fix(website): scale Hub preview height with browser text 2026-11-20 16:03:17 +01:00
Mohamed Boudra 41b65254e9 fix(website): wrap Hub source labels with larger text 2026-11-20 15:53:22 +01:00
Mohamed Boudra 609ef901c9 fix(website): keep Hub pricing tooltips inside their cards 2026-11-20 15:45:19 +01:00
Mohamed Boudra 57d1a61bad fix(website): show the selected Hub preview immediately 2026-11-20 15:36:35 +01:00
Mohamed Boudra d64d45a00b fix(website): preserve focus and labels in Hub showcase tabs 2026-11-20 15:25:40 +01:00
Mohamed Boudra b0d0c40a27 fix(website): address Hub refresh review findings 2026-11-20 15:14:05 +01:00
Mohamed Boudra 7a590f6c44 fix(website): keep navigation and plugin carousels within the page frame 2026-11-20 14:59:41 +01:00
Mohamed Boudra fa5d915364 fix(website): align Hub examples and docs with service behavior 2026-11-20 14:53:45 +01:00
Mohamed Boudra a15c8af302 website: prevent font-swap wrap jank and remove left bar on /hub source pills 2026-11-20 14:53:45 +01:00
Mohamed Boudra 37a513ea3d website: interactive source showcase on /hub automations section 2026-11-20 14:53:45 +01:00
Mohamed Boudra 35bc541bda style(website): tighten display-scale Paseo Hub lockup gap 2026-11-20 14:53:45 +01:00
Mohamed Boudra f34aa469c5 feat(website): replace Hub Discord demo with animated Slack mockup 2026-11-20 14:53:45 +01:00
Mohamed Boudra ef00b7fc41 feat(website): derive landing page plugin count from published registry 2026-11-20 14:53:45 +01:00
Mohamed Boudra 750be237e3 style(website): remove hairline rails from header and hero bands 2026-11-20 14:53:44 +01:00
Mohamed Boudra c7e000bb1a feat(website): use Plus Jakarta Sans for display titles 2026-11-20 14:53:44 +01:00
Mohamed Boudra 576048ebb8 chore(website): remove forced eyebrow numbering and redundant section eyebrows 2026-11-20 14:53:44 +01:00
Mohamed Boudra fd579a249a feat(website): unify page frame, rails, section rhythm, and hairline grids across home and /hub 2026-11-20 14:53:44 +01:00
Mohamed Boudra 2c69f5a5d2 chore(website): simplify homepage Hub flow layout and remove highlight cards 2026-11-20 14:53:44 +01:00
Mohamed Boudra 78a7508e3d chore(website): align Hub automation source copy and team visibility wording 2026-11-20 14:53:44 +01:00
Mohamed Boudra 0d436b1ae6 feat(website): refresh Paseo Hub page and add homepage Hub entry points 2026-11-20 14:53:44 +01:00
paseo-bot[bot] c853f98b90 fix(server): wait for restored checkout status on concurrent reads (#10304)
Co-authored-by: paseo-bot[bot] <266920839+paseo-bot[bot]@users.noreply.github.com>
2026-11-20 12:45:08 +00:00
Mohamed Boudra c3da87ee4c Support Gitea, Forgejo, and Codeberg change request watches (#10280)
* feat(server): add Gitea, Forgejo, and Codeberg support for change request watches

Implement the Gitea-family ChangeRequestSource using cwd-free tea login list and tea api --login -i requests, inspecting HTTP status codes directly on stdout/stderr rather than treating exit code 0 alone as success.

Reuse the shared per-host bounded poller for concurrency limits, 429 Retry-After pauses, and exponential backoff. Combine commit statuses and Actions tasks (including approval-held runs via need_approval and cross-repo waiting shadows) with mid-pagination headSha validation, and paginate comments, reviews, and inline review comments with bounded fan-out and quiet-poll caching.

* fix(server): address review findings on Gitea watch pagination, check sharing, and runs fetch

- Read /pulls/:index/reviews/:id/comments in a single request instead of a page loop because Gitea ignores page/limit on that endpoint and omits X-Total-Count/Link headers.
- Paginate /commits/:sha/status using the X-Total-Count response header instead of body total_count (which Gitea sets to the page length).
- Extract shared pure Gitea check schemas, shadow detection, rerun selection, and tea login matching into gitea-checks.ts imported by both gitea-service.ts and gitea-change-requests.ts.
- Remove the redundant /actions/runs fetch from the watch adapter because watch checks carry no action_required trait and approval-held tasks/pending shadows already map to pending.

* fix(server): preserve Gitea watch identity, checks, and backoff

* fix(server): route Gitea watches by base URL and retain complete updates

* fix(server): reconcile Gitea checks by job and refresh watch logins

* fix(server): validate Gitea and Forgejo Actions job responses

* fix(server): classify canceled native Actions statuses as neutral

* fix(server): drain failed Gitea polls before releasing host slots

* fix(server): let admitted Gitea polls finish with low quota

* fix(server): normalize Gitea watch URLs and refresh inline replies

* test(server): cover late Gitea rate limits across recovery windows
2026-11-20 18:41:41 +07:00
Mohamed Boudra 2298effb0b Support multi-forge change request watches and GitLab merge request watches (#10279)
* feat(server): add multi-forge routing and GitLab support for change request watches

Route change request watch URLs host-first through ForgeResolver (cloud host match plus cached async CLI auth probe) before delegating path canonicalization and polling to the matched forge adapter, while sharing adapter instances with workspace reads.

Persist the resolved forge id on saved watch records (defaulting legacy records to github) so daemon restarts recover active watches directly by forge without probing hosts during outages, and keep unknown-forge records intact rather than aborting boot.

Add the GitLab ChangeRequestSource using cwd-free glab api --hostname calls, bounded per-host polling and rate-limit/error backoff, head-pipeline job/bridge checks with mid-pagination headSha verification, discussions/comments, and observable GitLab approval transition updates without manufacturing a GitHub reviewDecision.

* fix(server): address review findings on GitLab watch rate limits, approvals, and legacy recovery

- Decide rate limits from HTTP status codes only on parsed glab responses so MR titles, comments, or IIDs mentioning 429 or rate limit never trip false host pauses.
- Remove the duplicate in-memory approval baseline and counter in favor of immutable GitLab approval system notes enriched with /approvals counts only on new notes, keeping seenActivity as the single persisted owner.
- Infer forge from URL shape when a persisted record omits forge so GitLab watches survive an older-daemon downgrade/upgrade cycle without probing.

* fix(server): handle GitLab locked merge state and custom-port glab host keys

- Pass the bare hostname to glab auth status and glab api --hostname (matching ForgeResolver.resolveHost and glab's api_host config) while preserving host:port in the canonical URL and description.
- Map GitLab's transient locked merge-in-progress state to open so watches keep polling until merged or closed.

* fix(server): preserve accurate GitLab watch updates and offline unsubscribe

* fix(server): validate GitLab watch project addresses and retain approval updates

* fix(server): honor GitLab watch profiles written by glab login

* fix(server): refresh authenticated GitLab watch profiles

* fix(server): keep GitLab poll access checks on merge requests

* fix(server): use GitLab MR access and enforce host pauses on every request

* fix(server): let admitted polls finish and retry denied GitLab reads

* fix(server): give quota-limited change request watches a turn

* fix(server): recover from shared forge quotas one poll at a time

* fix(server): rotate watches after failed quota recovery attempts
2026-11-20 18:05:10 +07:00
Mohamed Boudra a7fed94e51 Keep the Mac Explorer toggle in place (#10297)
Keep one titlebar toggle mounted while Explorer opens and closes. Reserve its footprint in the active rail so native pointer clicks and the header tab sequence work, and verify clearance from the Windows window controls.
2026-11-20 17:42:38 +07:00
140 changed files with 14261 additions and 4798 deletions
+10
View File
@@ -6651,6 +6651,15 @@
"url": "https://github.com/sponsors/ayuhito"
}
},
"node_modules/@fontsource-variable/plus-jakarta-sans": {
"version": "5.3.0",
"resolved": "https://registry.npmjs.org/@fontsource-variable/plus-jakarta-sans/-/plus-jakarta-sans-5.3.0.tgz",
"integrity": "sha512-/l/4r0yyWK9JzAlmA0LiYgGgmJe/Gswt4jTJEzr5QhJfwMbvJZDmYWyW0M4X7yCK69BajMVlV/Lx8g7WDc1+sw==",
"license": "OFL-1.1",
"funding": {
"url": "https://github.com/sponsors/ayuhito"
}
},
"node_modules/@getpaseo/app": {
"resolved": "packages/app",
"link": true
@@ -41479,6 +41488,7 @@
"@cloudflare/vite-plugin": "^1.29.1",
"@cloudflare/workers-types": "^4.20260317.1",
"@fontsource-variable/geist": "^5.3.0",
"@fontsource-variable/plus-jakarta-sans": "^5.3.0",
"@getpaseo/protocol": "*",
"@tanstack/react-router": "^1.170.16",
"@tanstack/react-start": "^1.168.26",
@@ -1,4 +1,4 @@
import { expect, type Page } from "@playwright/test";
import { expect, test, type Page } from "@playwright/test";
import { openChangesPanel } from "./branch-switcher";
export async function restoreArchivedWorkspace(page: Page): Promise<void> {
@@ -32,7 +32,11 @@ export async function expectCommittedFile(page: Page, filename: string): Promise
}
export async function expectCommittedFileAfterReload(page: Page, filename: string): Promise<void> {
await expectCommittedFile(page, filename);
await page.reload();
await expectCommittedFile(page, filename);
await test.step("See the committed file immediately after Restore", async () => {
await expectCommittedFile(page, filename);
});
await test.step("Reload and see the same committed file", async () => {
await page.reload();
await expectCommittedFile(page, filename);
});
}
+1
View File
@@ -66,6 +66,7 @@
[role="slider"],
[role="menuitem"],
[tabindex],
[data-window-no-drag],
[contenteditable="true"] {
-webkit-app-region: no-drag !important;
}
@@ -24,6 +24,9 @@ import { isNative } from "@/constants/platform";
*/
export const WINDOW_CONTENT_DATASET = { "window-content": "" };
/** Reserves a clickable area for a control mounted outside the titlebar rail. */
export const WINDOW_NO_DRAG_DATASET = { "window-no-drag": "" };
export const titlebarDragSurfaceStyle: React.CSSProperties = {
cursor: "default",
// @ts-expect-error — WebkitAppRegion is not in CSSProperties
@@ -27,6 +27,7 @@ const NO_SHORTCUT: ShortcutKey[] = [];
interface CompactHeaderProps {
/** The leading island: the sidebar menu, or a back button. */
navigation: "menu" | "back";
inDesktopTitlebar?: boolean;
/** Back button action. Defaults to navigating back. */
onBack?: () => void;
title?: string;
@@ -49,6 +50,7 @@ interface CompactHeaderProps {
*/
export function CompactHeader({
navigation,
inDesktopTitlebar = false,
onBack,
title,
titleTestID,
@@ -58,22 +60,28 @@ export function CompactHeader({
}: CompactHeaderProps) {
const insets = useSafeAreaInsets();
const inTopBand = useTopBand() !== null;
const usesTitlebarHeight = inTopBand || inDesktopTitlebar;
const rootStyle = useMemo(
() => [
styles.root,
{
paddingTop: insets.top + (inTopBand ? 0 : HEADER_TOP_PADDING_MOBILE),
paddingTop: insets.top + (usesTitlebarHeight ? 0 : HEADER_TOP_PADDING_MOBILE),
marginLeft: insets.left,
marginRight: insets.right,
},
],
[inTopBand, insets.top, insets.left, insets.right],
[usesTitlebarHeight, insets.top, insets.left, insets.right],
);
return (
<IconButtonChromeProvider value="header-island">
<View style={rootStyle}>
<View style={inTopBand ? styles.topBandRow : styles.row}>
<View
style={[
usesTitlebarHeight ? styles.titlebarRow : styles.row,
inDesktopTitlebar && styles.desktopTitlebarDividerSpace,
]}
>
<View style={styles.island}>
{navigation === "menu" ? <SidebarMenuToggle /> : <BackButton onBack={onBack} />}
</View>
@@ -155,12 +163,16 @@ const styles = StyleSheet.create((theme) => ({
alignItems: "center",
gap: theme.spacing[2],
},
topBandRow: {
titlebarRow: {
height: HEADER_INNER_HEIGHT,
flexDirection: "row",
alignItems: "center",
gap: theme.spacing[2],
},
desktopTitlebarDividerSpace: {
borderBottomWidth: theme.borderWidth[1],
borderBottomColor: "transparent",
},
titleGroup: {
flex: 1,
minWidth: 0,
@@ -20,8 +20,6 @@ afterEach(async () => {
await act(async () => root.render(null));
usePanelStore.setState(initialPanel, true);
});
const noop = () => {};
const explorerState = { expanded: false };
const geometry: WindowLayout = {
bounds: { x: 0, y: 0, width: window.innerWidth, height: window.innerHeight },
verticalBarEdge: "trailing",
@@ -42,9 +40,8 @@ it("updates compact header actions on panel changes without rendering the worksp
title="Workspace"
subtitle="Project"
isSubtitleDistinct
onToggleExplorer={noop}
explorerToggleLabel="Explorer"
explorerToggleAccessibilityState={explorerState}
explorerAction={null}
inDesktopTitlebar={false}
tabSwitcher={null}
headerVariant="full"
>
@@ -1,11 +1,6 @@
import { Fragment, useMemo, type ReactNode } from "react";
import { useTranslation } from "react-i18next";
import { usePanelStore } from "@/stores/panel-store";
import { CompactHeader } from "@/components/headers/compact-header";
import {
EXPLORER_TOGGLE_KEYS,
WorkspaceExplorerToggle,
} from "@/screens/workspace/workspace-explorer-toggle";
import { WorkspaceHeaderProjectRow } from "@/screens/workspace/workspace-header-project-row";
import {
useWindowLayout,
@@ -23,10 +18,9 @@ interface CompactWorkspaceHeaderProps {
title: string;
subtitle: string;
isSubtitleDistinct: boolean;
onToggleExplorer: () => void;
explorerToggleLabel: string;
explorerToggleAccessibilityState: { expanded: boolean };
explorerAction: ReactNode;
tabSwitcher: ReactNode;
inDesktopTitlebar: boolean;
/** Workspace overflow menu. */
children: ReactNode;
headerVariant: "compact" | "full";
@@ -40,17 +34,15 @@ export function CompactWorkspaceHeader({
title,
subtitle,
isSubtitleDistinct,
onToggleExplorer,
explorerToggleLabel,
explorerToggleAccessibilityState,
explorerAction,
children,
tabSwitcher,
inDesktopTitlebar,
serverId,
headerVariant,
isRouteFocused,
isCompact,
}: CompactWorkspaceHeaderProps) {
const { t } = useTranslation();
const actionsInBar = resolveWorkspaceActionPlacement(useWindowLayout()) === "vertical-bar";
const projectRow = useMemo(
() => (
@@ -65,16 +57,7 @@ export function CompactWorkspaceHeader({
const symbols = {
"tab-count": tabSwitcher,
overflow: children,
explorer: (
<WorkspaceExplorerToggle
onPress={onToggleExplorer}
label={explorerToggleLabel}
tooltipLabel={t("workspace.tabs.explorerSidebar.toggle")}
tooltipKeys={EXPLORER_TOGGLE_KEYS}
accessibilityState={explorerToggleAccessibilityState}
mobile
/>
),
explorer: explorerAction,
};
const actions = resolveWorkspaceBarActions(headerVariant).map((symbol) => (
<Fragment key={symbol}>{symbols[symbol]}</Fragment>
@@ -85,6 +68,7 @@ export function CompactWorkspaceHeader({
{headerVariant === "compact" ? (
<CompactHeader
navigation="menu"
inDesktopTitlebar={inDesktopTitlebar}
title={title}
titleTestID="workspace-header-title"
subtitle={projectRow}
@@ -1,47 +1,37 @@
import { useMemo } from "react";
import { useTranslation } from "react-i18next";
import { PanelRight } from "lucide-react-native";
import { type StyleProp, type ViewStyle } from "react-native";
import { withUnistyles } from "react-native-unistyles";
import { HeaderToggleButton } from "@/components/headers/header-toggle-button";
import { View, type StyleProp, type ViewStyle } from "react-native";
import { StyleSheet, withUnistyles } from "react-native-unistyles";
import { WINDOW_NO_DRAG_DATASET } from "@/components/desktop/titlebar-drag-region";
import { HeaderToggleButton, headerIconSlotStyle } from "@/components/headers/header-toggle-button";
import { SidebarCloseButton } from "@/components/headers/sidebar-close-button";
import {
extraMutedIconColorMapping,
iconButtonChromeGlyphSize,
mutedIconColorMapping,
} from "@/components/ui/icon-button-chrome";
import { WORKSPACE_SECONDARY_HEADER_HEIGHT } from "@/constants/layout";
import { useHasWindowChromeObstruction } from "@/utils/desktop-window";
import type { ShortcutKey } from "@/utils/format-shortcut";
const ThemedPanelRight = withUnistyles(PanelRight);
export const EXPLORER_TOGGLE_KEYS: ShortcutKey[] = ["mod", "E"];
const EXPLORER_TOGGLE_KEYS: ShortcutKey[] = ["mod", "E"];
interface WorkspaceExplorerToggleProps {
onPress: () => void;
label: string;
tooltipLabel: string;
tooltipKeys: ShortcutKey[];
accessibilityState: { expanded: boolean };
mobile: boolean;
style?: StyleProp<ViewStyle>;
}
export type WorkspaceExplorerToggleOwner = "mobile" | "header" | "window";
export function resolveWorkspaceExplorerToggleOwner({
isMobile,
hasMacTrafficLights,
}: {
isMobile: boolean;
hasMacTrafficLights: boolean;
}): WorkspaceExplorerToggleOwner {
if (isMobile) return "mobile";
return hasMacTrafficLights ? "window" : "header";
}
export function WorkspaceExplorerToggle({
function WorkspaceExplorerToggle({
onPress,
label,
tooltipLabel,
tooltipKeys,
accessibilityState,
mobile,
style,
@@ -51,7 +41,7 @@ export function WorkspaceExplorerToggle({
testID="workspace-explorer-toggle"
onPress={onPress}
tooltipLabel={tooltipLabel}
tooltipKeys={tooltipKeys}
tooltipKeys={EXPLORER_TOGGLE_KEYS}
tooltipSide="left"
style={style}
accessible
@@ -68,42 +58,97 @@ export function WorkspaceExplorerToggle({
);
}
interface DesktopWorkspaceExplorerToggleProps extends Omit<WorkspaceExplorerToggleProps, "mobile"> {
owner: WorkspaceExplorerToggleOwner;
export function useWorkspaceExplorerControls({
hasWorkspace,
compact,
focusMode,
expanded,
onToggle,
}: {
hasWorkspace: boolean;
compact: boolean;
focusMode: boolean;
expanded: boolean;
onToggle: () => void;
}) {
const { t } = useTranslation();
const hasLeadingWindowControls = useHasWindowChromeObstruction("top-left");
const inDesktopTitlebar = hasLeadingWindowControls && hasWorkspace && !compact && !focusMode;
return useMemo(() => {
const props = {
label: expanded
? t("workspace.tabs.explorerSidebar.close")
: t("workspace.tabs.explorerSidebar.open"),
tooltipLabel: t("workspace.tabs.explorerSidebar.toggle"),
onPress: onToggle,
accessibilityState: { expanded },
};
if (inDesktopTitlebar) {
// Keep the button in the header Tab order. The active rail carves its slot out of the drag region.
const headerSlot = expanded ? null : (
<View
pointerEvents="none"
style={[headerIconSlotStyle.slot, styles.headerAction]}
dataSet={WINDOW_NO_DRAG_DATASET}
/>
);
return {
inDesktopTitlebar,
headerAction: headerSlot,
compactAction: headerSlot,
dockAction: (
<View
pointerEvents="none"
style={[headerIconSlotStyle.slot, styles.dockAction]}
dataSet={WINDOW_NO_DRAG_DATASET}
/>
),
titlebarAction: (
<View pointerEvents="box-none" style={styles.titlebarSlot}>
<WorkspaceExplorerToggle {...props} mobile={false} />
</View>
),
};
}
return {
inDesktopTitlebar,
headerAction: compact ? null : (
<WorkspaceExplorerToggle {...props} mobile={false} style={styles.headerAction} />
),
compactAction: <WorkspaceExplorerToggle {...props} mobile />,
dockAction: compact ? (
<SidebarCloseButton
label={props.label}
onPress={onToggle}
testID="workspace-explorer-toggle"
accessibilityState={props.accessibilityState}
/>
) : null,
titlebarAction: null,
};
}, [compact, expanded, inDesktopTitlebar, onToggle, t]);
}
export function WorkspaceHeaderExplorerToggle({
owner,
accessibilityState,
style,
...toggleProps
}: DesktopWorkspaceExplorerToggleProps) {
if (owner === "mobile" || (owner === "window" && accessibilityState.expanded)) return null;
return (
<WorkspaceExplorerToggle
{...toggleProps}
accessibilityState={accessibilityState}
mobile={false}
style={style}
/>
);
}
export function WorkspaceExplorerSidebarToggle({
owner,
...toggleProps
}: DesktopWorkspaceExplorerToggleProps) {
if (owner === "header") return null;
if (owner === "mobile") {
// The compact Explorer is an overlay like the compact agent list, so it closes with the same X.
return (
<SidebarCloseButton
label={toggleProps.label}
onPress={toggleProps.onPress}
testID="workspace-explorer-toggle"
accessibilityState={toggleProps.accessibilityState}
/>
);
}
return <WorkspaceExplorerToggle {...toggleProps} mobile={false} />;
}
const styles = StyleSheet.create((theme) => ({
headerAction: {
marginRight: { xs: 0, md: -theme.spacing[2] },
},
dockAction: {
// The dock divider is absolutely positioned. Match the other headers' content center.
marginBottom: theme.borderWidth[1],
},
titlebarSlot: {
position: "absolute",
top: 0,
right: theme.spacing[1],
height: WORKSPACE_SECONDARY_HEADER_HEIGHT,
// Center with the bordered workspace header and Explorer tabs row.
borderBottomWidth: theme.borderWidth[1],
borderBottomColor: "transparent",
justifyContent: "center",
zIndex: 1,
},
}));
@@ -157,17 +157,8 @@ import {
} from "@/screens/workspace/workspace-desktop-tabs-row";
import { useDesktopBrowserNewTabRequests } from "@/desktop/browser/new-tab-requests";
import type { WorkspaceTabDescriptor } from "@/screens/workspace/workspace-tabs-types";
import {
resolveWorkspaceExplorerToggleOwner,
EXPLORER_TOGGLE_KEYS,
WorkspaceExplorerSidebarToggle,
WorkspaceHeaderExplorerToggle,
} from "@/screens/workspace/workspace-explorer-toggle";
import {
useHasWindowChromeObstruction,
WindowChromeRegion,
WindowChromeSafeArea,
} from "@/utils/desktop-window";
import { useWorkspaceExplorerControls } from "@/screens/workspace/workspace-explorer-toggle";
import { WindowChromeRegion, WindowChromeSafeArea } from "@/utils/desktop-window";
import {
resolveWorkspaceHeaderRenderState,
type WorkspaceHeaderCheckoutState,
@@ -1058,12 +1049,8 @@ function WorkspaceScreenContent({
const isMobile = useIsCompactFormFactor();
const canRenderDesktopPaneSplits = supportsDesktopPaneSplits();
const layoutMode = useWorkspaceLayoutStore((state) => state.layoutMode);
const hasMacTrafficLights = useHasWindowChromeObstruction("top-left");
const explorerToggleOwner = resolveWorkspaceExplorerToggleOwner({
isMobile,
hasMacTrafficLights,
});
const isFocusModeEnabled = usePanelStore((state) => state.desktop.focusModeEnabled);
const desktopFocusModeEnabled = isFocusModeEnabled && !isMobile;
const toggleFocusMode = usePanelStore((state) => state.toggleFocusMode);
const normalizedServerId = useMemo(() => trimNonEmpty(decodeSegment(serverId)) ?? "", [serverId]);
@@ -1308,11 +1295,6 @@ function WorkspaceScreenContent({
explorerOpen: isExplorerSidebarShowing,
});
const explorerSidebarToggleAccessibilityState = useMemo(
() => ({ expanded: isExplorerSidebarShowing }),
[isExplorerSidebarShowing],
);
useEffect(() => {
// Back dismisses the compact overlay only. On a wide native layout the
// explorer is a tab, `showMobileAgent` has no rendered consumer, and
@@ -1820,9 +1802,6 @@ function WorkspaceScreenContent({
}),
[t],
);
const explorerSidebarToggleLabel = isExplorerSidebarShowing
? t("workspace.tabs.explorerSidebar.close")
: t("workspace.tabs.explorerSidebar.open");
const activeTabKey = useMemo(() => activeTabId ?? "", [activeTabId]);
const handleCreateDraftTab = useCallback(
@@ -3228,6 +3207,13 @@ function WorkspaceScreenContent({
workspaceKey: persistenceKey,
});
const explorerControls = useWorkspaceExplorerControls({
hasWorkspace: !!workspaceDirectory,
compact: isMobile,
focusMode: desktopFocusModeEnabled,
expanded: isExplorerSidebarShowing,
onToggle: handleToggleExplorerSidebar,
});
const headerRight = useMemo(
() => (
<View style={styles.headerRight}>
@@ -3254,17 +3240,7 @@ function WorkspaceScreenContent({
{workspaceDirectory ? (
<>
<WorkspaceActions serverId={normalizedServerId} cwd={workspaceDirectory} />
{workspaceActionsInBar ? null : (
<WorkspaceHeaderExplorerToggle
owner={explorerToggleOwner}
onPress={handleToggleExplorerSidebar}
label={explorerSidebarToggleLabel}
tooltipLabel={t("workspace.tabs.explorerSidebar.toggle")}
tooltipKeys={EXPLORER_TOGGLE_KEYS}
style={styles.compactHeaderActionButton}
accessibilityState={explorerSidebarToggleAccessibilityState}
/>
)}
{workspaceActionsInBar ? null : explorerControls.headerAction}
</>
) : null}
</View>
@@ -3279,12 +3255,8 @@ function WorkspaceScreenContent({
scriptActions,
handleViewScriptTerminal,
handleOpenUrlInBrowserTab,
handleToggleExplorerSidebar,
explorerSidebarToggleLabel,
explorerSidebarToggleAccessibilityState,
explorerToggleOwner,
explorerControls.headerAction,
workspaceActionsInBar,
t,
],
);
@@ -3292,25 +3264,6 @@ function WorkspaceScreenContent({
() => shouldShowWorkspaceScreenHeader({ isFocusModeEnabled, isMobile }),
[isFocusModeEnabled, isMobile],
);
const renderExplorerSidebarHeaderAction = useCallback(
() => (
<WorkspaceExplorerSidebarToggle
owner={explorerToggleOwner}
onPress={handleToggleExplorerSidebar}
label={explorerSidebarToggleLabel}
tooltipLabel={t("workspace.tabs.explorerSidebar.toggle")}
tooltipKeys={EXPLORER_TOGGLE_KEYS}
accessibilityState={explorerSidebarToggleAccessibilityState}
/>
),
[
explorerSidebarToggleAccessibilityState,
explorerSidebarToggleLabel,
explorerToggleOwner,
handleToggleExplorerSidebar,
t,
],
);
const createTerminalDisabled = useMemo(
() => createTerminalMutation.isPending || pendingTerminalCreateInput !== null,
[createTerminalMutation.isPending, pendingTerminalCreateInput],
@@ -3333,10 +3286,6 @@ function WorkspaceScreenContent({
],
);
const focusedPaneIdOrUndefined = useMemo(() => focusedPaneId ?? undefined, [focusedPaneId]);
const desktopFocusModeEnabled = useMemo(
() => isFocusModeEnabled && !isMobile,
[isFocusModeEnabled, isMobile],
);
const workspaceFloatingPanelPortalHostName = useMemo(
() =>
`${WORKSPACE_FLOATING_PANEL_PORTAL_HOST_PREFIX}:${normalizedServerId}:${normalizedWorkspaceId}`,
@@ -3460,14 +3409,13 @@ function WorkspaceScreenContent({
isRouteFocused={isRouteFocused}
isCompact={isMobile}
tabSwitcher={tabSwitcher}
inDesktopTitlebar={explorerControls.inDesktopTitlebar}
explorerAction={explorerControls.compactAction}
isLoading={isWorkspaceHeaderLoading}
title={workspaceHeaderTitle}
subtitle={workspaceHeaderSubtitle}
isSubtitleDistinct={isWorkspaceHeaderSubtitleDistinct}
serverId={normalizedServerId}
onToggleExplorer={handleToggleExplorerSidebar}
explorerToggleLabel={explorerSidebarToggleLabel}
explorerToggleAccessibilityState={explorerSidebarToggleAccessibilityState}
>
<WorkspaceHeaderMenuMobile
pane={paneTabs?.actions.pane}
@@ -3493,20 +3441,19 @@ function WorkspaceScreenContent({
},
[
renderWorkspaceTabSwitcher,
explorerControls.inDesktopTitlebar,
explorerControls.compactAction,
isFocusModeEnabled,
toggleFocusMode,
canOpenImportSheet,
compactHeaderScripts,
createTerminalDisabled,
currentBranchName,
explorerSidebarToggleAccessibilityState,
explorerSidebarToggleLabel,
handleCopyBranchName,
handleCopyWorkspacePath,
handleCreateBrowserTab,
handleCreateTerminalWithProfile,
handleOpenSetupTab,
handleToggleExplorerSidebar,
isMobile,
isRouteFocused,
isWorkspaceHeaderLoading,
@@ -3734,7 +3681,7 @@ function WorkspaceScreenContent({
onExitFocusMode={toggleFocusMode}
onReorderTabsInPane={handleReorderTabsInPane}
buildPaneContentModel={buildDesktopPaneContentModel}
headerAction={renderExplorerSidebarHeaderAction()}
headerAction={explorerControls.dockAction}
/>
);
return (
@@ -3775,7 +3722,7 @@ function WorkspaceScreenContent({
toggleFocusMode,
handleReorderTabsInPane,
buildDesktopPaneContentModel,
renderExplorerSidebarHeaderAction,
explorerControls.dockAction,
desktopFocusModeEnabled,
]);
@@ -3849,6 +3796,7 @@ function WorkspaceScreenContent({
onReorderTabsInPane={handleReorderTabsInPane}
onSplitPane={handleSplitPane}
>
{explorerControls.titlebarAction}
{workspaceCenterColumn}
{sharedExplorer}
</WorkspaceTabDragScope>
@@ -3986,12 +3934,6 @@ const styles = StyleSheet.create((theme) => ({
md: theme.spacing[2],
},
},
compactHeaderActionButton: {
marginRight: {
xs: 0,
md: -theme.spacing[2],
},
},
compactHeaderMenuCluster: {
flexDirection: "row",
alignItems: "center",
@@ -1,10 +1,5 @@
import { buildDesktopFrameStyle } from "@/components/ui/combobox-frame-style";
import {
WorkspaceHeaderExplorerToggle,
WorkspaceExplorerSidebarToggle,
} from "./workspace-explorer-toggle";
import { describe, expect, it } from "vitest";
import { SidebarCloseButton } from "@/components/headers/sidebar-close-button";
import { resolveWorkspaceTabChipBackdrop } from "@/screens/workspace/workspace-tab-chip-backdrop";
import { darkPureBlackTheme, darkTheme, lightTheme } from "@/styles/theme";
import {
@@ -190,37 +185,6 @@ describe("retainWorkspaceTabMeasuredWidth", () => {
});
});
describe("Explorer toggle ownership", () => {
const toggleProps = {
onPress: () => {},
label: "Close Explorer sidebar",
tooltipLabel: "Toggle Explorer sidebar",
tooltipKeys: [],
accessibilityState: { expanded: true },
};
it("keeps only the header toggle when window controls do not obstruct it", () => {
expect(WorkspaceHeaderExplorerToggle({ ...toggleProps, owner: "header" })).not.toBeNull();
expect(WorkspaceExplorerSidebarToggle({ ...toggleProps, owner: "header" })).toBeNull();
});
it("keeps the dock toggle for window-owned and compact overlay chrome", () => {
for (const owner of ["window", "mobile"] as const) {
expect(WorkspaceHeaderExplorerToggle({ ...toggleProps, owner })).toBeNull();
expect(WorkspaceExplorerSidebarToggle({ ...toggleProps, owner })).not.toBeNull();
}
});
it("closes the compact overlay with the same X as the compact agent list", () => {
expect(WorkspaceExplorerSidebarToggle({ ...toggleProps, owner: "mobile" })?.type).toBe(
SidebarCloseButton,
);
expect(WorkspaceExplorerSidebarToggle({ ...toggleProps, owner: "window" })?.type).not.toBe(
SidebarCloseButton,
);
});
});
describe("resolveWorkspaceTabChipBackdrop", () => {
const themes = { light: lightTheme, dark: darkTheme, pureBlack: darkPureBlackTheme };
const rails = {
@@ -0,0 +1,164 @@
import type { Locator, Page } from "@playwright/test";
import { expect, test } from "../../app/e2e/support/fixtures";
import { gotoWorkspace } from "../../app/e2e/support/helpers/launcher";
function explorerSidebar(page: Page) {
return page.getByTestId("workspace-explorer-sidebar").filter({ visible: true });
}
async function useDesktopWindowChrome(page: Page, mode: "native-mac" | "custom-windows") {
await page.addInitScript((windowChromeMode) => {
Object.assign(window, {
paseoDesktop: {
platform: windowChromeMode === "native-mac" ? "darwin" : "win32",
windowChromeMode,
invoke: async () => null,
events: { on: async () => () => undefined },
getPendingOpenProject: async () => null,
window: {
getCurrentWindow: () => ({
isFullscreen: async () => false,
onResized: async () => () => undefined,
}),
},
},
});
}, mode);
}
function explorerToggle(page: Page, expanded: boolean) {
return page.getByRole("button", {
name: expanded ? "Close Explorer sidebar" : "Open Explorer sidebar",
exact: true,
expanded,
});
}
async function recordExplorerToggle(button: Locator) {
const recording = await button.evaluateHandle((target) => {
const measure = () => {
const glyph = target.querySelector("svg")?.getBoundingClientRect();
return {
connected: target.isConnected,
x: glyph?.x,
y: glyph?.y,
width: glyph?.width,
height: glyph?.height,
};
};
const before = measure();
const frames: ReturnType<typeof measure>[] = [];
const done = new Promise<void>((resolve) => {
target.addEventListener(
"click",
() => {
const start = performance.now();
const sample = () => {
frames.push(measure());
if (performance.now() - start < 300) requestAnimationFrame(sample);
else resolve();
};
requestAnimationFrame(sample);
},
{ once: true },
);
});
return { before, frames, done };
});
try {
await button.click();
return await recording.evaluate(async ({ before, frames, done }) => {
await done;
return { before, frames };
});
} finally {
await recording.dispose();
}
}
async function expectExplorerToggleHasNativeClickArea(toggle: Locator) {
const regions = await toggle.evaluate((button) => {
const rect = button.getBoundingClientRect();
const x = rect.x + rect.width / 2;
const y = rect.y + rect.height / 2;
return [
...document.querySelectorAll('[style*="app-region"], [data-window-no-drag], [role="button"]'),
]
.filter((element) => {
const bounds = element.getBoundingClientRect();
return bounds.left <= x && x < bounds.right && bounds.top <= y && y < bounds.bottom;
})
.map((element) => getComputedStyle(element).getPropertyValue("-webkit-app-region"))
.filter((region) => region === "drag" || region === "no-drag");
});
expect(regions).toContain("drag");
expect(regions.at(-1)).toBe("no-drag");
}
async function expectExplorerToggleInHeaderTabOrder(page: Page, expanded: boolean) {
const toggle = explorerToggle(page, expanded);
await toggle.focus();
await page.keyboard.press("Tab");
await expect(page.getByRole("button", { name: "Workspace actions", exact: true })).toBeFocused();
await page.keyboard.press("Shift+Tab");
await expect(toggle).toBeFocused();
}
async function expectExplorerToggleToHoldPosition(page: Page, expanded: boolean) {
const toggle = explorerToggle(page, expanded);
await expect(toggle).toBeVisible();
await expectExplorerToggleHasNativeClickArea(toggle);
const { before, frames } = await recordExplorerToggle(toggle);
await expect(explorerToggle(page, !expanded)).toBeVisible();
expect(before.width).toBeGreaterThan(0);
expect(frames.find((frame) => JSON.stringify(frame) !== JSON.stringify(before))).toBeUndefined();
}
test("keeps the Mac Explorer toggle in place across open and close", async ({
page,
withWorkspace,
}) => {
await page.setViewportSize({ width: 1440, height: 900 });
await useDesktopWindowChrome(page, "native-mac");
const { workspaceId } = await withWorkspace();
await gotoWorkspace(page, workspaceId);
await expectExplorerToggleInHeaderTabOrder(page, false);
await expectExplorerToggleToHoldPosition(page, false);
await expectExplorerToggleInHeaderTabOrder(page, true);
await expectExplorerToggleToHoldPosition(page, true);
await page.setViewportSize({ width: 930, height: 900 });
await expectExplorerToggleToHoldPosition(page, false);
await expectExplorerToggleToHoldPosition(page, true);
});
async function expectClearOfWindowControls(page: Page, action: Locator) {
const minimize = page.getByRole("button", { name: "Minimize window", exact: true });
await expect(minimize).toBeVisible();
await expect(action).toBeVisible();
const controlBounds = await minimize.boundingBox();
const actionBounds = await action.boundingBox();
expect(actionBounds!.x + actionBounds!.width).toBeLessThanOrEqual(controlBounds!.x);
}
test("keeps the Explorer actions clear of Windows controls", async ({ page, withWorkspace }) => {
await page.setViewportSize({ width: 1440, height: 900 });
await useDesktopWindowChrome(page, "custom-windows");
const { workspaceId } = await withWorkspace();
await gotoWorkspace(page, workspaceId);
const open = explorerToggle(page, false);
await expectClearOfWindowControls(page, open);
await open.click();
const close = explorerToggle(page, true);
const newExplorerTab = explorerSidebar(page).getByRole("button", {
name: "New tab",
exact: true,
});
await expectClearOfWindowControls(page, close);
await expectClearOfWindowControls(page, newExplorerTab);
await close.click();
await expect(open).toBeVisible();
});
@@ -1,11 +1,12 @@
import { readFile } from "node:fs/promises";
import { join } from "node:path";
import { FORGE_IDS } from "@getpaseo/protocol/forge-manifest";
import type { Logger } from "pino";
import { z } from "zod";
import type { ChangeRequestRouter } from "../../../services/change-request-router.js";
import {
changeRequestStatusSchema,
type ChangeRequestSnapshot,
type ChangeRequestSource,
} from "../../../services/change-request-source.js";
import type { AgentMessageDelivery } from "../agent-messages/index.js";
import type {
@@ -15,13 +16,17 @@ import type {
import { writeJsonFileAtomic } from "../../atomic-file.js";
const DIGEST_WINDOW_MS = 30_000;
const watchGroupSchema = z.object({
const LEGACY_DEFAULT_FORGE = "github";
const LEGACY_INFERENCE_FORGES = ["github", "gitlab"] as const;
const persistedWatchGroupSchema = z.object({
forge: z.string().min(1).optional(),
url: z.url(),
snapshot: changeRequestStatusSchema,
seenActivity: z.array(z.string()),
watchers: z.array(z.object({ agentId: z.string(), startedAt: z.string().optional() })),
});
type WatchGroup = z.infer<typeof watchGroupSchema>;
type PersistedWatchGroup = z.infer<typeof persistedWatchGroupSchema>;
type WatchGroup = Omit<PersistedWatchGroup, "forge"> & { forge: string };
type Watcher = WatchGroup["watchers"][number];
interface DigestWindow {
dueAt: number;
@@ -35,7 +40,7 @@ interface Observation {
release(): void;
}
interface Dependencies {
source: ChangeRequestSource;
router: ChangeRequestRouter;
paseoHome: string;
logger: Logger;
isActive(agentId: string): Promise<boolean>;
@@ -73,7 +78,7 @@ function describeUpdate(group: WatchGroup, next: ChangeRequestSnapshot) {
}
for (const activity of next.activity) {
if (seen.has(activity.id)) continue;
changes.push(`New ${activity.kind}: ${activity.url}`);
changes.push(activity.message ?? `New ${activity.kind}: ${activity.url}`);
seen.add(activity.id);
}
if (next.state !== "open") changes.push(`Change request ${next.state}.`);
@@ -85,6 +90,7 @@ export type ChangeRequestWatches = ReturnType<typeof createChangeRequestWatches>
export function createChangeRequestWatches(deps: Dependencies) {
const file = join(deps.paseoHome, "change-request-watches.json");
const groups = new Map<string, WatchGroup>();
const unrestored: WatchGroup[] = [];
const observations = new Map<string, Observation>();
const registrations = new Map<string, number>();
let mutations = Promise.resolve();
@@ -156,32 +162,47 @@ export function createChangeRequestWatches(deps: Dependencies) {
}
}
function withdraw(agentId: string, url?: string): boolean {
let removed = false;
for (const [address, window] of windows) {
if (url && address !== url) continue;
removed = window.recipients.delete(agentId) || removed;
function withdraw(agentId: string, matches: (url: string) => boolean): string | undefined {
let withdrawn: string | undefined;
for (const [url, window] of windows) {
if (!window.recipients.has(agentId) || !matches(url)) continue;
window.recipients.delete(agentId);
withdrawn ??= url;
if (!window.recipients.size) {
clearTimeout(window.timer);
windows.delete(address);
windows.delete(url);
}
}
const queued = deps
.messages()
.withdrawPending(
agentId,
(source) => source.kind === "change-request-update" && (!url || source.url === url),
);
return removed || queued > 0;
deps.messages().withdrawPending(agentId, (source) => {
if (source.kind !== "change-request-update" || !matches(source.url)) return false;
withdrawn ??= source.url;
return true;
});
return withdrawn;
}
function withdrawByInput(agentId: string, input: string): string | undefined {
const trimmed = input.trim();
const candidates = new Set([trimmed]);
for (const forge of FORGE_IDS) {
const source = deps.router.source(forge);
if (!source) continue;
try {
candidates.add(source.resolve(trimmed));
} catch {
// This source does not recognize the URL.
}
}
return withdraw(agentId, (url) => candidates.has(url));
}
async function commit(...updates: WatchGroup[]): Promise<void> {
const next = new Map(groups);
for (const group of updates) next.set(group.url, group);
await writeJsonFileAtomic(
file,
[...next.values()].filter(({ watchers }) => watchers.length),
);
await writeJsonFileAtomic(file, [
...[...next.values()].filter(({ watchers }) => watchers.length),
...unrestored,
]);
for (const group of updates) {
const previous = groups.get(group.url);
// An in-flight subscription still needs the committed baseline and its observation.
@@ -195,7 +216,20 @@ export function createChangeRequestWatches(deps: Dependencies) {
}
}
function syncBackgroundWork({ url, watchers }: WatchGroup, previous: Watcher[] = []): void {
function describeWatch(forge: string, url: string): string {
const source = deps.router.source(forge);
if (!source) return url;
try {
return source.describe(url);
} catch {
return url;
}
}
function syncBackgroundWork(
{ forge, url, watchers }: WatchGroup,
previous: Watcher[] = [],
): void {
if (previous === watchers) return;
const current = new Set(watchers);
for (const watcher of previous) {
@@ -209,7 +243,7 @@ export function createChangeRequestWatches(deps: Dependencies) {
deps.backgroundWork.setDaemonBackgroundWork({
...backgroundWorkKey(watcher.agentId, url),
kind: "monitor",
description: deps.source.describe(url),
description: describeWatch(forge, url),
startedAt: watcher.startedAt ?? new Date().toISOString(),
stop: async () => {
await unsubscribe(watcher.agentId, url, watcher);
@@ -218,9 +252,13 @@ export function createChangeRequestWatches(deps: Dependencies) {
}
}
function observe(url: string): Observation {
function observe(forge: string, url: string): Observation {
const existing = observations.get(url);
if (existing) return existing;
const source = deps.router.source(forge);
if (!source) {
throw new Error(`Change request watches are not supported for ${forge}.`);
}
let resolve!: (snapshot: ChangeRequestSnapshot) => void;
let reject!: (error: unknown) => void;
const ready = new Promise<ChangeRequestSnapshot>((accept, fail) => {
@@ -228,7 +266,7 @@ export function createChangeRequestWatches(deps: Dependencies) {
reject = fail;
});
void ready.catch(() => undefined);
const release = deps.source.observe(url, {
const release = source.observe(url, {
knownActivity: () => new Set(groups.get(url)?.seenActivity),
snapshot: (snapshot) =>
serialize(async () => {
@@ -266,14 +304,14 @@ export function createChangeRequestWatches(deps: Dependencies) {
}),
error(error) {
if (!observation.stale) {
deps.logger.warn({ err: error, url }, "Change request observation became stale");
deps.logger.warn({ err: error, url, forge }, "Change request observation became stale");
}
observation.stale = true;
if (!groups.has(url)) {
reject(error);
stopObserving(url);
}
deps.logger.debug({ err: error, url }, "Change request observation failed");
deps.logger.debug({ err: error, url, forge }, "Change request observation failed");
},
});
const observation: Observation = {
@@ -288,16 +326,62 @@ export function createChangeRequestWatches(deps: Dependencies) {
return observation;
}
async function subscribe(agentId: string, input: string) {
if (closed) throw new Error("Change request watches are closed");
const url = deps.source.resolve(input);
if (recoveryError)
throw new Error("Change request watches could not recover.", { cause: recoveryError });
function matchActiveGroup(input: string): { forge: string; url: string } | null {
const trimmed = input.trim();
const direct = groups.get(trimmed);
if (direct) return { forge: direct.forge, url: direct.url };
const sourcesTried = new Set<string>();
for (const group of groups.values()) {
if (sourcesTried.has(group.forge)) continue;
sourcesTried.add(group.forge);
const source = deps.router.source(group.forge);
if (!source) continue;
try {
const canonical = source.resolve(trimmed);
const matched = groups.get(canonical);
if (matched && matched.forge === group.forge) {
return { forge: matched.forge, url: matched.url };
}
} catch {
// Input did not belong to this forge.
}
}
return null;
}
function subscribe(agentId: string, input: string) {
if (closed) return Promise.reject(new Error("Change request watches are closed"));
if (recoveryError) {
return Promise.reject(
new Error("Change request watches could not recover.", { cause: recoveryError }),
);
}
const active = matchActiveGroup(input);
if (active) {
return subscribeResolved(agentId, active.forge, active.url);
}
return deps.router
.resolve(input)
.then(({ forge, url }) => subscribeResolved(agentId, forge, url));
}
function subscribeResolved(agentId: string, forge: string, url: string) {
registrations.set(url, (registrations.get(url) ?? 0) + 1);
try {
const existing = groups.get(url);
const initial = existing ? { ...existing.snapshot, activity: [] } : await observe(url).ready;
return await serialize(async () => {
const existing = groups.get(url);
const finish = () => {
const remaining = registrations.get(url)! - 1;
if (remaining) {
registrations.set(url, remaining);
} else {
registrations.delete(url);
if (!groups.get(url)?.watchers.length) {
groups.delete(url);
stopObserving(url);
}
}
};
const commitSubscription = (initial: ChangeRequestSnapshot) =>
serialize(async () => {
if (closed || !(await deps.isActive(agentId))) throw new Error("Agent is no longer active");
const group = groups.get(url);
const { activity, ...initialStatus } = initial;
@@ -305,6 +389,7 @@ export function createChangeRequestWatches(deps: Dependencies) {
const subscribed = snapshot.state === "open";
if (subscribed && !group?.watchers.some((watcher) => watcher.agentId === agentId)) {
await commit({
forge: group?.forge ?? forge,
url,
snapshot,
seenActivity: group?.seenActivity ?? activity.map(({ id }) => id),
@@ -322,21 +407,13 @@ export function createChangeRequestWatches(deps: Dependencies) {
checks: snapshot.checks,
reviewDecision: snapshot.reviewDecision,
subscribed,
stale: observations.get(url)?.stale ?? false,
stale: observations.get(url)?.stale ?? Boolean(existing),
};
});
} finally {
const remaining = registrations.get(url)! - 1;
if (remaining) {
registrations.set(url, remaining);
} else {
registrations.delete(url);
if (!groups.get(url)?.watchers.length) {
groups.delete(url);
stopObserving(url);
}
}
}
const pending = existing
? commitSubscription({ ...existing.snapshot, activity: [] })
: observe(forge, url).ready.then(commitSubscription);
return pending.finally(finish);
}
function removeWatcher(group: WatchGroup, agentId: string): Promise<void> {
@@ -355,15 +432,15 @@ export function createChangeRequestWatches(deps: Dependencies) {
throw new Error("Background work is no longer available to stop");
}
if (group && watcher) await removeWatcher(group, agentId);
const withdrawn = withdraw(agentId, url);
return { url, removed: Boolean(watcher) || withdrawn };
const withdrawn = withdraw(agentId, (address) => address === url);
return { url, removed: Boolean(watcher || withdrawn) };
});
}
function archive(agentId: string): Promise<void> {
return serialize(async () => {
if (closed) return;
withdraw(agentId);
withdraw(agentId, () => true);
const updates: WatchGroup[] = [];
for (const group of groups.values()) {
const watchers = group.watchers.filter((watcher) => watcher.agentId !== agentId);
@@ -373,6 +450,20 @@ export function createChangeRequestWatches(deps: Dependencies) {
});
}
function inferLegacyForge(url: string): string {
for (const candidate of LEGACY_INFERENCE_FORGES) {
const source = deps.router.source(candidate);
if (!source) continue;
try {
source.resolve(url);
return candidate;
} catch {
// URL does not match this forge's canonical path shape.
}
}
return LEGACY_DEFAULT_FORGE;
}
return {
async start() {
const active: WatchGroup[] = [];
@@ -382,8 +473,12 @@ export function createChangeRequestWatches(deps: Dependencies) {
if (error.code === "ENOENT") return "[]";
throw error;
});
const restored = z.array(watchGroupSchema).parse(JSON.parse(stored));
for (const group of restored) {
const restored = z.array(persistedWatchGroupSchema).parse(JSON.parse(stored));
for (const record of restored) {
const group: WatchGroup = {
...record,
forge: record.forge ?? inferLegacyForge(record.url),
};
if (group.snapshot.state !== "open") {
pruned = true;
continue;
@@ -393,7 +488,17 @@ export function createChangeRequestWatches(deps: Dependencies) {
if (await deps.isActive(watcher.agentId)) watchers.push(watcher);
}
pruned ||= watchers.length !== group.watchers.length;
if (watchers.length) active.push({ ...group, watchers });
if (!watchers.length) continue;
const nextGroup = { ...group, watchers };
if (!deps.router.source(nextGroup.forge)) {
deps.logger.warn(
{ forge: nextGroup.forge, url: nextGroup.url },
"Skipping persisted change request watch for unsupported forge",
);
unrestored.push(nextGroup);
continue;
}
active.push(nextGroup);
}
} catch (error) {
recoveryError = error;
@@ -402,7 +507,7 @@ export function createChangeRequestWatches(deps: Dependencies) {
}
if (pruned) {
try {
await writeJsonFileAtomic(file, active);
await writeJsonFileAtomic(file, [...active, ...unrestored]);
} catch (error) {
deps.logger.warn({ err: error, file }, "Could not prune archived change request watches");
}
@@ -410,12 +515,24 @@ export function createChangeRequestWatches(deps: Dependencies) {
for (const group of active) {
groups.set(group.url, group);
syncBackgroundWork(group);
observe(group.url);
try {
observe(group.forge, group.url);
} catch (error) {
deps.logger.warn(
{ err: error, forge: group.forge, url: group.url },
"Could not start observing restored change request watch",
);
}
}
},
subscribe,
unsubscribe(agentId: string, input: string) {
return unsubscribe(agentId, deps.source.resolve(input));
async unsubscribe(agentId: string, input: string) {
const active = matchActiveGroup(input);
if (active) return unsubscribe(agentId, active.url);
const withdrawn = await serialize(async () => withdrawByInput(agentId, input));
if (withdrawn) return { url: withdrawn, removed: true };
const { url } = await deps.router.resolve(input);
return unsubscribe(agentId, url);
},
archive,
async close() {
@@ -1,16 +1,18 @@
import { mkdir, mkdtemp, readFile, rename, rm } from "node:fs/promises";
import { mkdir, mkdtemp, readFile, rename, rm, writeFile } from "node:fs/promises";
import { join } from "node:path";
import pino from "pino";
import { afterEach, expect, test, vi } from "vitest";
import { createChangeRequestWatches } from "./index.js";
import { AgentBackgroundWorkStore } from "../background-work/index.js";
import { createAgentMessageDelivery, parseAgentMessages } from "../agent-messages/index.js";
import type { ChangeRequestRouter } from "../../../services/change-request-router.js";
import type {
ChangeRequestSnapshot,
ChangeRequestSource,
} from "../../../services/change-request-source.js";
const url = "https://github.com/owner/repo/pull/42";
const gitlabUrl = "https://gitlab.com/org/sub/app/-/merge_requests/9";
const reviewUrl = url + "#pullrequestreview-1";
const initial: ChangeRequestSnapshot = {
state: "open",
@@ -31,13 +33,19 @@ async function createTestHome() {
function createHarness(
home: string,
{ isActive = async (_id: string) => true, observationFails = false } = {},
{
isActive = async (_id: string) => true,
observationFails = false,
resolveFails = false,
extraSources = {} as Record<string, ChangeRequestSource>,
} = {},
) {
const observations = new Map<string, Parameters<ChangeRequestSource["observe"]>[1]>();
const backgroundWork = new AgentBackgroundWorkStore();
const busy = new Set<string>();
const turns: { recipientId: string; prompt: string }[] = [];
const listeners = new Set<(id: string) => void>();
const resolveCalls: string[] = [];
const messages = createAgentMessageDelivery({
isRunning: (id) => busy.has(id),
subscribe(listener) {
@@ -52,10 +60,16 @@ function createHarness(
throw error;
},
});
const watches = createChangeRequestWatches({
source: {
resolve: (input) => input,
describe: () => "owner/repo #42",
function createFakeSource(
describe: (address: string) => string,
accepts: (input: string) => boolean,
): ChangeRequestSource {
return {
resolve: (input) => {
if (!accepts(input)) throw new Error("Unsupported URL for fake forge");
return input.replace(/\/+$/, "");
},
describe,
observe(address, callbacks) {
observations.set(address, callbacks);
queueMicrotask(() => {
@@ -64,7 +78,34 @@ function createHarness(
});
return () => observations.delete(address);
},
};
}
const sources: Record<string, ChangeRequestSource> = {
github: createFakeSource(
() => "owner/repo #42",
(input) => input.includes("/pull/"),
),
gitlab: createFakeSource(
() => "org/sub/app !9",
(input) => input.includes("/merge_requests/"),
),
...extraSources,
};
const router: ChangeRequestRouter = {
async resolve(input) {
resolveCalls.push(input);
if (resolveFails) throw new Error("Host probe failed");
const forge = input.includes("gitlab") ? "gitlab" : "github";
const source = sources[forge];
if (!source) throw new Error(`Unsupported forge: ${forge}`);
return { forge, url: source.resolve(input) };
},
source(forge) {
return sources[forge] ?? null;
},
};
const watches = createChangeRequestWatches({
router,
paseoHome: home,
logger: pino({ enabled: false }),
isActive,
@@ -78,6 +119,7 @@ function createHarness(
messages,
watches,
backgroundWork,
resolveCalls,
idle(id: string) {
busy.delete(id);
for (const listener of listeners) listener(id);
@@ -255,6 +297,47 @@ test("can withdraw a terminal digest after its observation has stopped", async (
}
});
test.each([0, 32_000])(
"withdraws a terminal update without a host probe after %i ms",
async (elapsed) => {
vi.useFakeTimers();
const home = await createTestHome();
const enterpriseUrl = "https://github.example.com/owner/repo/pull/42";
const { activity: _activity, ...snapshot } = initial;
await writeFile(
join(home, "change-request-watches.json"),
JSON.stringify([
{
forge: "github",
url: enterpriseUrl,
snapshot,
seenActivity: [],
watchers: [{ agentId: "first" }],
},
]),
);
const h = createHarness(home, { resolveFails: true });
try {
h.busy.add("first");
await h.watches.start();
await h.observations.get(enterpriseUrl)!.snapshot({ ...initial, state: "merged" });
expect(h.observations.has(enterpriseUrl)).toBe(false);
await vi.advanceTimersByTimeAsync(elapsed);
await expect(h.watches.unsubscribe("first", `${enterpriseUrl}/`)).resolves.toEqual({
url: enterpriseUrl,
removed: true,
});
expect(h.resolveCalls).toEqual([]);
h.idle("first");
await vi.advanceTimersByTimeAsync(32_000);
expect(h.turns).toEqual([]);
} finally {
await h.close();
await rm(home, { recursive: true, force: true });
}
},
);
test("retains the current observation as the last subscriber leaves and a new one joins", async () => {
const home = await createTestHome();
const h = createHarness(home);
@@ -343,3 +426,119 @@ test("recovers active watches even when pruning archived watchers cannot be writ
await rm(home, { recursive: true, force: true });
}
});
test("persists forge ids, restores legacy GitHub watches without probing, and preserves unknown forges", async () => {
const home = await createTestHome();
const file = join(home, "change-request-watches.json");
const legacyRecord = {
url,
snapshot: {
state: "open",
headSha: "aaa",
checksState: "pending",
checks: [],
reviewDecision: null,
},
seenActivity: [],
watchers: [{ agentId: "legacy-agent", startedAt: "2026-01-01T00:00:00.000Z" }],
};
const unknownForgeRecord = {
forge: "futureforge",
url: "https://future.example.com/team/repo/cr/5",
snapshot: legacyRecord.snapshot,
seenActivity: [],
watchers: [{ agentId: "future-agent", startedAt: "2026-01-01T00:00:00.000Z" }],
};
const strippedGitLabRecord = {
url: gitlabUrl,
snapshot: legacyRecord.snapshot,
seenActivity: [],
watchers: [{ agentId: "gitlab-agent", startedAt: "2026-01-01T00:00:00.000Z" }],
};
await writeFile(
file,
JSON.stringify([legacyRecord, strippedGitLabRecord, unknownForgeRecord]),
"utf8",
);
const h = createHarness(home, { resolveFails: true });
try {
await h.watches.start();
expect(h.resolveCalls).toEqual([]);
expect(h.backgroundWork.list("legacy-agent")).toEqual([
expect.objectContaining({ description: "owner/repo #42", kind: "monitor" }),
]);
expect(h.backgroundWork.list("gitlab-agent")).toEqual([
expect.objectContaining({ description: "org/sub/app !9", kind: "monitor" }),
]);
expect(h.observations.has(url)).toBe(true);
expect(h.observations.has(gitlabUrl)).toBe(true);
// Unsubscribing an active watch succeeds even when host resolution is temporarily down.
await expect(h.watches.unsubscribe("legacy-agent", `${url}/`)).resolves.toEqual({
url,
removed: true,
});
expect(h.backgroundWork.list("legacy-agent")).toEqual([]);
const persisted = JSON.parse(await readFile(file, "utf8")) as Array<{
forge?: string;
url: string;
}>;
expect(persisted).toEqual([
expect.objectContaining({ forge: "gitlab", url: gitlabUrl }),
unknownForgeRecord,
]);
} finally {
await h.close();
await rm(home, { recursive: true, force: true });
}
});
test("watches multiple forges concurrently with forge-native descriptions and custom approval messages", async () => {
vi.useFakeTimers();
const home = await createTestHome();
const file = join(home, "change-request-watches.json");
const h = createHarness(home);
try {
await h.watches.start();
await h.watches.subscribe("agent-1", url);
await h.watches.subscribe("agent-1", gitlabUrl);
expect(h.backgroundWork.list("agent-1").map((item) => item.description)).toEqual([
"owner/repo #42",
"org/sub/app !9",
]);
const persisted = JSON.parse(await readFile(file, "utf8")) as Array<{
forge?: string;
url: string;
}>;
expect(persisted.map(({ forge, url: entryUrl }) => ({ forge, url: entryUrl }))).toEqual([
{ forge: "github", url },
{ forge: "gitlab", url: gitlabUrl },
]);
await h.observations.get(gitlabUrl)!.snapshot({
...initial,
activity: [
{
id: "approval-note:77",
kind: "approval",
url: `${gitlabUrl}#note_77`,
message: `Merge request approved by @alice (1/1 approvals): ${gitlabUrl}#note_77`,
},
],
});
await vi.advanceTimersByTimeAsync(32_000);
expect(h.turns).toEqual([
{
recipientId: "agent-1",
prompt: expect.stringContaining(
`Merge request approved by @alice (1/1 approvals): ${gitlabUrl}#note_77`,
),
},
]);
} finally {
await h.close();
await rm(home, { recursive: true, force: true });
}
});
@@ -2728,13 +2728,19 @@ function createToolCatalog(
if (options.changeRequestWatches) {
const watches = options.changeRequestWatches;
const inputSchema = { url: z.string().trim().min(1).describe("URL of a GitHub pull request.") };
const inputSchema = {
url: z
.string()
.trim()
.min(1)
.describe("URL of a pull request or merge request on a supported forge."),
};
registerTool(
"subscribe_change_request",
{
title: "Watch change request",
description:
"Watch a pull request for check failures, passing checks, new comments, reviews, and closure. Returns the current state and sends future updates after your current turn.",
"Watch a pull request or merge request for check failures, passing checks, new comments, reviews, approvals, and closure. Returns the current state and sends future updates after your current turn.",
inputSchema,
outputSchema: {
url: z.string(),
+9 -2
View File
@@ -132,6 +132,9 @@ export async function fanOutReconciledWorkspaceUpdates(input: {
import { VoiceAssistantWebSocketServer, isDaemonOriginAllowed } from "./websocket-server.js";
import { WorkspaceSetupRuntime } from "./workspace-setup-runtime.js";
import { createWorkspaceLabelService } from "./workspace-labels/index.js";
import { createChangeRequestRouter } from "../services/change-request-router.js";
import { createForgeService } from "../services/forge-registry.js";
import { createForgeResolver } from "../services/forge-resolver.js";
import { createGitHubService } from "../services/github-service.js";
import { createPaseoWorktree as createRegisteredPaseoWorktree } from "./paseo-worktree-service.js";
import { createWorkspaceProvisioningService } from "./session/workspace-provisioning/workspace-provisioning-service.js";
@@ -954,12 +957,15 @@ export async function createPaseoDaemon(
workspaceRegistry,
});
const github = createGitHubService();
const forgeResolver = createForgeResolver({
createService: (forge) => (forge === "github" ? github : createForgeService(forge)),
});
const workspaceGitService = new WorkspaceGitServiceImpl({
logger,
paseoHome: config.paseoHome,
worktreesRoot: config.worktreesRoot,
deps: {
forgeOverrides: { github },
forgeResolver,
},
});
const workspaceRuntimeStore = createWorkspaceRuntimeStore();
@@ -1472,7 +1478,7 @@ export async function createPaseoDaemon(
await scheduleService.start();
const changeRequestWatches = createChangeRequestWatches({
source: github.changeRequests,
router: createChangeRequestRouter({ forgeResolver }),
backgroundWork: agentManager,
paseoHome: config.paseoHome,
logger,
@@ -2056,6 +2062,7 @@ export async function createPaseoDaemon(
if (wsServer) {
await wsServer.close();
}
forgeResolver.dispose();
await serviceProxy.stopStandalone();
// Force-drop remaining sockets so httpServer.close() resolves promptly.
// We've already closed wsServer (which sent ws-layer close frames) and
@@ -6,12 +6,7 @@ import { PassThrough } from "node:stream";
import path from "node:path";
import { fileURLToPath } from "node:url";
import pino from "pino";
import {
PROVIDER_CAPABILITIES,
type ProviderEvent,
type ProviderPrompt,
type ProviderRegistration,
} from "@getpaseo/plugin/server/provider";
import type { ProviderEvent, ProviderRegistration } from "@getpaseo/plugin/server/provider";
import { afterEach, describe, expect, it, vi } from "vitest";
import type { AgentStreamEvent } from "../agent/agent-sdk-types.js";
import { PluginAgentClientRegistry } from "../agent/plugin-provider.js";
@@ -363,232 +358,6 @@ register(${JSON.stringify(guardUrl)});`;
await adapters.shutdown();
await runtime.stopAll();
});
// The muse provider runs against a fake MSP host (injected through the
// provider's command override), but everything above it is real: the plugin
// subprocess, PluginRuntime's capability enforcement, and the
// PluginAgentClientRegistry path an agent actually uses. On a muse build
// that does not negotiate `session.subsession`, the daemon fails the whole
// provider connection when the child is projected, so both tests fail
// before the fix.
async function startMuseRuntime() {
const fakeMuse = fileURLToPath(
new URL("../../../../../plugins/muse-provider/test/fake-muse.mjs", import.meta.url),
);
const directory = fileURLToPath(
new URL("../../../../../plugins/muse-provider/", import.meta.url),
);
const runtime = createTestRuntime({}, undefined, "0.11.0");
await runtime.startPlugin("muse-provider", directory);
const [metadata] = runtime.getProviderRegistrations("muse-provider");
expect(metadata).toBeDefined();
return { runtime, metadata: metadata!, fakeMuse };
}
async function startMuseClient(extraEnv: Record<string, string>) {
const { runtime, metadata, fakeMuse } = await startMuseRuntime();
const adapters = new PluginAgentClientRegistry(pino({ level: "silent" }));
adapters.replace([
{
...adaptRuntimeProvider(runtime, "muse-provider", metadata),
command: metadata.command,
},
]);
const client = adapters.definitions()[metadata.id]!.createClient(pino({ level: "silent" }), {
command: { mode: "replace", argv: [process.execPath, fakeMuse] },
env: { MUSE_TEST_SCENARIO: "subagent", MUSE_TEST_CHILD: "tool", ...extraEnv },
});
return { runtime, adapters, client };
}
function hasSettledTurn(events: readonly AgentStreamEvent[]): boolean {
return events.some((event) => event.type === "turn_completed" || event.type === "turn_failed");
}
// Asserting on the settled turn (rather than polling only for completion)
// puts the provider's failure — e.g. "Provider parent session did not
// negotiate session.subsession" — in the test output.
async function expectTurnCompleted(events: readonly AgentStreamEvent[]): Promise<void> {
await expect.poll(() => hasSettledTurn(events)).toBe(true);
expect(events.filter((event) => event.type === "turn_failed")).toEqual([]);
expect(hasCompletedAgentTurn(events)).toBe(true);
}
function hasSubagentTimeline(events: readonly AgentStreamEvent[]): boolean {
return events.some(
(event) =>
event.type === "provider_subagent" &&
event.event.type === "timeline" &&
event.event.item.type === "assistant_message" &&
event.event.item.text.includes("SUBAGENT_PHASE0_OK"),
);
}
it("projects a muse subagent through PluginRuntime without failing the connection", async () => {
const { runtime, adapters, client } = await startMuseClient({});
try {
const events: AgentStreamEvent[] = [];
const session = await client.createSession({ provider: "muse", cwd: process.cwd() });
session.subscribe((event) => events.push(event));
await session.startTurn("dispatch a subagent", { clientMessageId: "muse-live" });
await expectTurnCompleted(events);
expect(hasSubagentTimeline(events)).toBe(true);
// The connection survives: a fresh session on the same provider opens
// and completes a turn instead of hitting a dead cached connection.
const second = await client.createSession({ provider: "muse", cwd: process.cwd() });
const secondEvents: AgentStreamEvent[] = [];
second.subscribe((event) => secondEvents.push(event));
await second.startTurn("again", { clientMessageId: "muse-live-2" });
await expectTurnCompleted(secondEvents);
await second.close();
await session.close();
} finally {
await adapters.shutdown();
await runtime.stopAll();
}
});
it("replays a muse subagent from history on resume without failing the connection", async () => {
const historyDirectory = await mkdtemp(path.join(tmpdir(), "paseo-muse-history-"));
temporaryDirectories.push(historyDirectory);
const { runtime, adapters, client } = await startMuseClient({
MUSE_TEST_HISTORY: path.join(historyDirectory, "native-history.ndjson"),
});
try {
const first = await client.createSession({ provider: "muse", cwd: process.cwd() });
const persistence = first.describePersistence();
expect(persistence).not.toBeNull();
await first.close();
// Seed old history without running a live subagent first, so this test
// reaches resume even when live child projection is broken.
await writeFile(
path.join(historyDirectory, "native-history.ndjson"),
JSON.stringify({
itemId: "historical-subagent",
revision: 1,
kind: "toolCall",
status: "completed",
tool: "subagent_spawn",
childSessionId: "fixture-child",
}) + "\n",
);
const resumed = await client.resumeSession(persistence!, { cwd: process.cwd() });
const resumedEvents: AgentStreamEvent[] = [];
resumed.subscribe((event) => resumedEvents.push(event));
// History replayed during resume is exposed through streamHistory.
const replayed: AgentStreamEvent[] = [];
for await (const event of resumed.streamHistory()) replayed.push(event);
expect(hasSubagentTimeline(replayed)).toBe(true);
await resumed.startTurn("continue", { clientMessageId: "muse-resumed" });
await expectTurnCompleted(resumedEvents);
await resumed.close();
} finally {
await adapters.shutdown();
await runtime.stopAll();
}
});
it("keeps other Muse sessions live when a parent closes during a child read", async () => {
const directory = await mkdtemp(path.join(tmpdir(), "paseo-muse-child-read-"));
temporaryDirectories.push(directory);
const requests = path.join(directory, "requests.ndjson");
const release = path.join(directory, "release");
const { runtime, metadata, fakeMuse } = await startMuseRuntime();
try {
const connection = await runtime.connectProvider("muse-provider", metadata.id, {
versions: [1],
capabilities: PROVIDER_CAPABILITIES,
launch: {
command: process.execPath,
args: [fakeMuse],
env: {
MUSE_TEST_SCENARIO: "subagent",
MUSE_TEST_CHILD: "tool",
MUSE_TEST_REQUESTS: requests,
MUSE_TEST_CHILD_READ_RELEASE: release,
},
},
});
const events: ProviderEvent[] = [];
connection.onEvent((event) => events.push(event));
for (const sessionId of ["closing", "sibling"]) {
await connection.send({
type: "session.open",
requestId: `open-${sessionId}`,
sessionId,
history: "skip",
config: { cwd: process.cwd(), env: {}, mcpServers: {}, settings: {}, persist: true },
});
await expect
.poll(() => events, { timeout: 5000 })
.toContainEqual(expect.objectContaining({ type: "session.ready", sessionId }));
}
const prompt: ProviderPrompt = {
clientMessageId: "spawn-child",
delivery: "auto",
input: { type: "message", content: [{ type: "text", text: "spawn a child" }] },
};
await connection.send({ type: "session.prompt", sessionId: "closing", prompt });
await expect
.poll(() => readFile(requests, "utf8"), { timeout: 5000 })
.toContain('"method":"session/read"');
// send() resolves after the runtime has accepted the close and removed
// the parent from its session table, while the child read is still pending.
await connection.send({
type: "session.close",
requestId: "close-parent",
sessionId: "closing",
});
await writeFile(release, "");
const closeSettled = (event: ProviderEvent) =>
(event.type === "request.completed" && event.requestId === "close-parent") ||
(event.type === "session.runtime_failed" && event.sessionId === "sibling");
await expect.poll(() => events.some(closeSettled), { timeout: 5000 }).toBe(true);
expect(
events.filter(
(event) => event.type === "session.runtime_failed" && event.sessionId === "sibling",
),
).toEqual([]);
expect(events).toContainEqual({ type: "request.completed", requestId: "close-parent" });
await connection.send({ type: "session.prompt", sessionId: "sibling", prompt });
await expect
.poll(() => events, { timeout: 5000 })
.toContainEqual(
expect.objectContaining({
type: "session.turn",
sessionId: "sibling",
state: "completed",
}),
);
} finally {
await writeFile(release, "");
await runtime.stopAll();
}
});
it("closes a Muse agent when the host exits without answering a child read", async () => {
const directory = await mkdtemp(path.join(tmpdir(), "paseo-muse-close-"));
temporaryDirectories.push(directory);
const requests = path.join(directory, "requests.ndjson");
const { runtime, adapters, client } = await startMuseClient({
MUSE_TEST_HANG: "session/read",
MUSE_TEST_REQUESTS: requests,
});
try {
const session = await client.createSession({ provider: "muse", cwd: process.cwd() });
await session.startTurn("spawn a child", { clientMessageId: "close-with-pending-read" });
await expect
.poll(() => readFile(requests, "utf8"), { timeout: 5000 })
.toContain('"method":"session/read"');
await expect(session.close()).resolves.toBeUndefined();
} finally {
await adapters.shutdown();
await runtime.stopAll();
}
});
it("runs a provider connection through the real plugin subprocess boundary", async () => {
const directory = await createPlugin(
@@ -2404,6 +2404,46 @@ describe("WorkspaceGitServiceImpl with workspace folders that no longer exist",
await service.dispose();
});
test("a snapshot read during restoration waits for fresh checkout facts", async () => {
const workspace = await createTemporaryFolder();
const git = createFolderBackedGit();
const started = createDeferred<void>();
const release = createDeferred<void>();
let holdRestoredRead = false;
const service = createService({
...git.deps,
getCheckoutSnapshotFacts: async (cwd: string) => {
if (holdRestoredRead) {
started.resolve();
await release.promise;
}
return git.deps.getCheckoutSnapshotFacts(cwd);
},
});
const subscription = service.registerWorkspace({ cwd: workspace }, vi.fn());
await waitForObservationToSettle(service, 1);
await rm(workspace, { recursive: true, force: true });
service.onWorkspaceStateMayHaveChanged(workspace);
await vi.advanceTimersByTimeAsync(1_000);
await waitForRefreshesToSettle(service);
expect((await service.getSnapshot(workspace)).git.isGit).toBe(false);
await advanceThroughDegradedPolls(service);
await waitForObservationToSettle(service, 0);
await mkdir(workspace);
holdRestoredRead = true;
const restoringRead = service.getSnapshot(workspace);
await started.promise;
const concurrentRead = service.getSnapshot(workspace);
release.resolve();
expect((await restoringRead).git.isGit).toBe(true);
expect((await concurrentRead).git.isGit).toBe(true);
subscription.unsubscribe();
await service.dispose();
});
test("a resumed workspace rebuilds observation from fresh facts, not the non-git facts cached while its folder was gone", async () => {
const workspace = await createTemporaryFolder();
const git = createFolderBackedGit();
@@ -422,6 +422,8 @@ interface WorkspaceGitServiceDependencies {
* fakes. Any forge not listed here is built (and cached once) by the registry.
*/
forgeOverrides?: Record<string, ForgeService>;
/** Shared forge resolver when callers share adapter instances with other services. */
forgeResolver?: ForgeResolver;
/** Resolves an SSH config alias to its HostName; defaults to `ssh -G`. */
resolveSshHostname?: SshHostnameResolver;
resolveAbsoluteGitDir: (cwd: string) => Promise<string | null>;
@@ -723,10 +725,12 @@ export class WorkspaceGitServiceImpl implements WorkspaceGitService {
this.fileObserver.subscribe.bind(this.fileObserver),
options.deps,
);
this.forgeResolver = createForgeResolver({
createService: (forge) => this.deps.forgeOverrides?.[forge] ?? createForgeService(forge),
resolveSshHostname: this.deps.resolveSshHostname,
});
this.forgeResolver =
this.deps.forgeResolver ??
createForgeResolver({
createService: (forge) => this.deps.forgeOverrides?.[forge] ?? createForgeService(forge),
resolveSshHostname: this.deps.resolveSshHostname,
});
}
resolveForge(cwd: string): Promise<ForgeResolution | null> {
@@ -834,9 +838,10 @@ export class WorkspaceGitServiceImpl implements WorkspaceGitService {
cwd = resolve(cwd);
const request = this.normalizeRefreshRequest(options, "getSnapshot");
const target = this.ensureWorkspaceTarget(cwd);
// The snapshot cached while the folder was gone can say "not git". Resume
// first, so a restored folder is read again instead of served from it.
if (target.folderMissing) {
// Restoration clears folderMissing before the fresh snapshot is ready.
if (target.folderRestorePromise) {
await target.folderRestorePromise;
} else if (target.folderMissing) {
await this.resumeWorkspaceIfFolderRestored(target);
}
if (!request.force && target.latestSnapshot) {
@@ -0,0 +1,230 @@
import { afterEach, describe, expect, it, vi } from "vitest";
import type { ChangeRequestSnapshot } from "./change-request-source.js";
import {
ChangeRequestRateLimitError,
createPerHostChangeRequestPoller,
parseCliHttpResponse,
parseRetryAfterMs,
} from "./change-request-poller.js";
const sampleSnapshot: ChangeRequestSnapshot = {
state: "open",
headSha: "abc123",
checksState: "passed",
checks: [],
reviewDecision: null,
activity: [],
};
afterEach(() => {
vi.useRealTimers();
});
describe("parseCliHttpResponse", () => {
it("parses status line, mixed line endings, redirect blocks, and JSON body", () => {
const raw = [
"HTTP/1.1 100 Continue\r\n\r\n",
"HTTP/2.0 200 OK\n",
"Content-Type: application/json\r\n",
"X-Next-Page: 2\r\n",
"Ratelimit-Remaining: 95\r\n",
"Ratelimit-Reset: 1700000120\r\n",
"\r\n",
'{"ok":true}',
].join("");
const parsed = parseCliHttpResponse(raw);
expect(parsed.status).toBe(200);
expect(parsed.headers.get("x-next-page")).toBe("2");
expect(parsed.headers.get("ratelimit-remaining")).toBe("95");
expect(parsed.body).toBe('{"ok":true}');
});
it("returns null status and raw body when headers are absent", () => {
const parsed = parseCliHttpResponse('{"ok":true}');
expect(parsed.status).toBeNull();
expect(parsed.headers.size).toBe(0);
expect(parsed.body).toBe('{"ok":true}');
});
});
describe("parseRetryAfterMs", () => {
it("parses Retry-After seconds and exhausted Ratelimit-Reset headers", () => {
const now = 1_700_000_000_000;
expect(parseRetryAfterMs(new Map([["retry-after", "45"]]), now)).toBe(now + 45_000);
expect(
parseRetryAfterMs(
new Map([
["ratelimit-remaining", "0"],
["ratelimit-reset", "1700000060"],
]),
now,
),
).toBe(1_700_000_060_000);
expect(
parseRetryAfterMs(
new Map([
["ratelimit-remaining", "50"],
["ratelimit-reset", "1700000060"],
]),
now,
),
).toBeNull();
});
});
describe("createPerHostChangeRequestPoller", () => {
it("bounds concurrent reads per host and drains waiting watches as slots free", async () => {
vi.useFakeTimers();
let active = 0;
let maxActive = 0;
const resolvers = new Map<string, () => void>();
const poller = createPerHostChangeRequestPoller({
hostOf: (url) => new URL(url).hostname,
maxConcurrencyPerHost: 2,
pollIntervalMs: 20_000,
async read({ url }) {
active += 1;
maxActive = Math.max(maxActive, active);
await new Promise<void>((resolve) => {
resolvers.set(url, resolve);
});
active -= 1;
return sampleSnapshot;
},
});
const received: string[] = [];
try {
for (const n of [1, 2, 3]) {
const url = `https://gitlab.com/org/repo/-/merge_requests/${n}`;
poller.observe(url, {
async snapshot() {
received.push(url);
},
error(error) {
throw error;
},
});
}
await vi.advanceTimersByTimeAsync(25);
expect(maxActive).toBe(2);
expect(resolvers.size).toBe(2);
resolvers.get("https://gitlab.com/org/repo/-/merge_requests/1")?.();
await vi.advanceTimersByTimeAsync(0);
expect(maxActive).toBe(2);
expect(resolvers.has("https://gitlab.com/org/repo/-/merge_requests/3")).toBe(true);
resolvers.get("https://gitlab.com/org/repo/-/merge_requests/2")?.();
resolvers.get("https://gitlab.com/org/repo/-/merge_requests/3")?.();
await vi.advanceTimersByTimeAsync(0);
expect(received).toHaveLength(3);
} finally {
poller.dispose();
}
});
it("backs off exponentially on transient errors and resets after a successful poll", async () => {
vi.useFakeTimers();
let calls = 0;
let shouldFail = true;
const poller = createPerHostChangeRequestPoller({
hostOf: (url) => new URL(url).hostname,
pollIntervalMs: 10_000,
maxErrorBackoffMs: 40_000,
async read() {
calls += 1;
if (shouldFail) throw new Error(`fail ${calls}`);
return sampleSnapshot;
},
});
const errors: unknown[] = [];
const snapshots: ChangeRequestSnapshot[] = [];
try {
poller.observe("https://gitlab.com/org/repo/-/merge_requests/1", {
async snapshot(s) {
snapshots.push(s);
},
error(err) {
errors.push(err);
},
});
await vi.advanceTimersByTimeAsync(25);
expect(calls).toBe(1);
expect(errors).toHaveLength(1);
// 1st failure -> 10s backoff
await vi.advanceTimersByTimeAsync(9_999);
expect(calls).toBe(1);
await vi.advanceTimersByTimeAsync(1);
expect(calls).toBe(2);
// 2nd failure -> 20s backoff
await vi.advanceTimersByTimeAsync(19_999);
expect(calls).toBe(2);
shouldFail = false;
await vi.advanceTimersByTimeAsync(1);
expect(calls).toBe(3);
expect(snapshots).toHaveLength(1);
// Reset to 10s base interval after success
await vi.advanceTimersByTimeAsync(10_000);
expect(calls).toBe(4);
} finally {
poller.dispose();
}
});
it("pauses all watches on a rate-limited host until resetAt and fast-fails new observers", async () => {
vi.useFakeTimers();
vi.setSystemTime(1_700_000_000_000);
let calls = 0;
const poller = createPerHostChangeRequestPoller({
hostOf: (url) => new URL(url).hostname,
pollIntervalMs: 10_000,
async read() {
calls += 1;
if (calls === 1) {
throw new ChangeRequestRateLimitError({
host: "gitlab.com",
resetAtMs: Date.now() + 60_000,
});
}
return sampleSnapshot;
},
});
const errors1: unknown[] = [];
const errors2: unknown[] = [];
const snapshots2: ChangeRequestSnapshot[] = [];
try {
poller.observe("https://gitlab.com/org/repo/-/merge_requests/1", {
async snapshot() {},
error(err) {
errors1.push(err);
},
});
await vi.advanceTimersByTimeAsync(25);
expect(calls).toBe(1);
expect(errors1[0]).toBeInstanceOf(ChangeRequestRateLimitError);
poller.observe("https://gitlab.com/org/repo/-/merge_requests/2", {
async snapshot(s) {
snapshots2.push(s);
},
error(err) {
errors2.push(err);
},
});
await vi.advanceTimersByTimeAsync(0);
expect(errors2[0]).toBeInstanceOf(ChangeRequestRateLimitError);
await vi.advanceTimersByTimeAsync(59_999);
expect(calls).toBe(1);
await vi.advanceTimersByTimeAsync(1);
expect(calls).toBe(3);
expect(snapshots2).toHaveLength(1);
} finally {
poller.dispose();
}
});
});
@@ -0,0 +1,362 @@
import type { ChangeRequestSnapshot, ChangeRequestSource } from "./change-request-source.js";
const DEFAULT_INITIAL_DELAY_MS = 25;
const DEFAULT_POLL_INTERVAL_MS = 20_000;
const DEFAULT_MAX_ERROR_BACKOFF_MS = 300_000;
const DEFAULT_MAX_CONCURRENCY_PER_HOST = 2;
const MIN_RATE_LIMIT_PAUSE_MS = 1_000;
const MAX_RATE_LIMIT_PAUSE_MS = 15 * 60_000;
export interface ParsedCliHttpResponse {
status: number | null;
headers: Map<string, string>;
body: string;
}
const HTTP_STATUS_PREFIX = /^HTTP\/\d(?:\.\d)?\s+(\d{3})[^\r\n]*\r?\n/;
const HEADER_BODY_SEPARATOR = /\r?\n\r?\n/;
/**
* Parse output from CLI API commands invoked with `-i` / `--include`.
* Consumes multiple leading HTTP response blocks (e.g. `100 Continue` or
* redirect headers) and returns the final status code, lowercased headers,
* and response body. Returns `status: null` when no HTTP header block is
* present.
*/
export function parseCliHttpResponse(raw: string): ParsedCliHttpResponse {
let remaining = raw.trimStart();
let status: number | null = null;
let headers = new Map<string, string>();
while (true) {
const statusMatch = HTTP_STATUS_PREFIX.exec(remaining);
if (!statusMatch) {
break;
}
const separatorMatch = HEADER_BODY_SEPARATOR.exec(remaining);
if (!separatorMatch) {
status = Number(statusMatch[1]);
headers = parseHeaderLines(remaining.slice(statusMatch[0].length));
remaining = "";
break;
}
status = Number(statusMatch[1]);
const headerBlock = remaining.slice(statusMatch[0].length, separatorMatch.index);
headers = parseHeaderLines(headerBlock);
remaining = remaining.slice(separatorMatch.index + separatorMatch[0].length);
}
return { status, headers, body: remaining.trim() };
}
function parseHeaderLines(block: string): Map<string, string> {
const headers = new Map<string, string>();
for (const line of block.split(/\r?\n/)) {
const colon = line.indexOf(":");
if (colon <= 0) continue;
const name = line.slice(0, colon).trim().toLowerCase();
const value = line.slice(colon + 1).trim();
if (!name) continue;
const existing = headers.get(name);
headers.set(name, existing ? `${existing}, ${value}` : value);
}
return headers;
}
function clampPauseUntil(targetMs: number, nowMs: number): number {
return Math.min(
Math.max(targetMs, nowMs + MIN_RATE_LIMIT_PAUSE_MS),
nowMs + MAX_RATE_LIMIT_PAUSE_MS,
);
}
/**
* Extract the timestamp (epoch ms) until which a host should pause polling
* based on `Retry-After` or exhausted `Ratelimit-Remaining` / `Ratelimit-Reset`
* headers. Returns null when no pause is signaled.
*/
export function parseRetryAfterMs(
headers: ReadonlyMap<string, string>,
nowMs: number,
options: { forceOnMissing?: boolean; defaultPauseMs?: number } = {},
): number | null {
const retryAfter = headers.get("retry-after");
if (retryAfter) {
const seconds = Number(retryAfter);
if (Number.isFinite(seconds) && seconds >= 0) {
return clampPauseUntil(nowMs + Math.ceil(seconds * 1_000), nowMs);
}
const parsedDate = Date.parse(retryAfter);
if (Number.isFinite(parsedDate)) {
return clampPauseUntil(parsedDate, nowMs);
}
}
const remainingRaw = headers.get("ratelimit-remaining") ?? headers.get("x-ratelimit-remaining");
const resetRaw = headers.get("ratelimit-reset") ?? headers.get("x-ratelimit-reset");
const remaining = remainingRaw !== undefined ? Number(remainingRaw) : Number.NaN;
const resetSec = resetRaw !== undefined ? Number(resetRaw) : Number.NaN;
if (
(options.forceOnMissing || (Number.isFinite(remaining) && remaining <= 1)) &&
Number.isFinite(resetSec) &&
resetSec > 0
) {
return clampPauseUntil(resetSec * 1_000, nowMs);
}
if (options.forceOnMissing) {
return clampPauseUntil(nowMs + (options.defaultPauseMs ?? 60_000), nowMs);
}
return null;
}
export class ChangeRequestRateLimitError extends Error {
readonly host: string;
readonly resetAtMs: number;
constructor(params: { host: string; resetAtMs: number; message?: string }) {
super(
params.message ??
`Change request polling for ${params.host} is rate-limited until ${new Date(params.resetAtMs).toISOString()}`,
);
this.name = "ChangeRequestRateLimitError";
this.host = params.host;
this.resetAtMs = params.resetAtMs;
}
}
export interface PerHostReadContext {
url: string;
host: string;
knownActivity(): ReadonlySet<string> | undefined;
isObserved(): boolean;
assertHostAvailable(): void;
deferPollsUntil(untilMs: number): void;
pauseHost(untilMs: number): void;
}
export interface PerHostChangeRequestPollerOptions {
hostOf(url: string): string;
read(context: PerHostReadContext): Promise<ChangeRequestSnapshot>;
now?: () => number;
initialDelayMs?: number;
pollIntervalMs?: number;
maxErrorBackoffMs?: number;
maxConcurrencyPerHost?: number;
onError?(error: unknown, host: string): void;
}
interface WatchedEntry {
url: string;
host: string;
callbacks: Parameters<ChangeRequestSource["observe"]>[1];
nextDueAt: number;
consecutiveErrors: number;
inFlight: boolean;
}
export interface PerHostChangeRequestPoller {
observe: ChangeRequestSource["observe"];
dispose(): void;
}
/**
* Bounded per-host polling loop shared by REST-backed forge watch adapters.
* Limits concurrent reads per host, applies exponential backoff on transient
* failures, and pauses all watches for a host when rate-limited.
*/
export function createPerHostChangeRequestPoller(
options: PerHostChangeRequestPollerOptions,
): PerHostChangeRequestPoller {
const now = options.now ?? Date.now;
const initialDelayMs = options.initialDelayMs ?? DEFAULT_INITIAL_DELAY_MS;
const pollIntervalMs = options.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS;
const maxErrorBackoffMs = options.maxErrorBackoffMs ?? DEFAULT_MAX_ERROR_BACKOFF_MS;
const maxConcurrencyPerHost = options.maxConcurrencyPerHost ?? DEFAULT_MAX_CONCURRENCY_PER_HOST;
const watches = new Map<string, WatchedEntry>();
const inFlightByHost = new Map<string, number>();
const pausesByHost = new Map<string, { pollsUntil: number; requestsUntil: number }>();
let timer: NodeJS.Timeout | null = null;
let disposed = false;
function clearTimer(): void {
if (timer) {
clearTimeout(timer);
timer = null;
}
}
function deferHost(host: string, untilMs: number, blockRequests: boolean): void {
const current = pausesByHost.get(host) ?? { pollsUntil: 0, requestsUntil: 0 };
pausesByHost.set(host, {
pollsUntil: Math.max(current.pollsUntil, untilMs),
requestsUntil: blockRequests
? Math.max(current.requestsUntil, untilMs)
: current.requestsUntil,
});
}
function hostPauseUntil(host: string, nowMs: number): number {
const pause = pausesByHost.get(host);
if (!pause) return 0;
if (pause.pollsUntil > nowMs) return pause.pollsUntil;
if (!pause.requestsUntil) pausesByHost.delete(host);
return 0;
}
function pollLimit(host: string): number {
// After a 429, admit one poll until it has delivered a full snapshot.
// This lets it use the reset quota without competing with another poll.
return pausesByHost.get(host)?.requestsUntil ? 1 : maxConcurrencyPerHost;
}
function armTimer(): void {
clearTimer();
if (disposed || watches.size === 0) return;
const nowMs = now();
let earliestDue = Number.POSITIVE_INFINITY;
for (const watch of watches.values()) {
if (watch.inFlight) continue;
if ((inFlightByHost.get(watch.host) ?? 0) >= pollLimit(watch.host)) continue;
const dueAt = Math.max(watch.nextDueAt, hostPauseUntil(watch.host, nowMs));
if (dueAt < earliestDue) {
earliestDue = dueAt;
}
}
if (!Number.isFinite(earliestDue)) return;
const delay = Math.max(0, earliestDue - nowMs);
timer = setTimeout(() => {
timer = null;
drainDueWatches();
}, delay);
timer.unref();
}
function drainDueWatches(): void {
if (disposed) return;
const nowMs = now();
for (const watch of watches.values()) {
if (watch.inFlight) continue;
const inFlightCount = inFlightByHost.get(watch.host) ?? 0;
if (inFlightCount >= pollLimit(watch.host)) continue;
const dueAt = Math.max(watch.nextDueAt, hostPauseUntil(watch.host, nowMs));
if (dueAt > nowMs) continue;
startPoll(watch);
}
armTimer();
}
function startPoll(watch: WatchedEntry): void {
watch.inFlight = true;
inFlightByHost.set(watch.host, (inFlightByHost.get(watch.host) ?? 0) + 1);
const isObserved = () => !disposed && watches.get(watch.url) === watch;
const recovering = Boolean(pausesByHost.get(watch.host)?.requestsUntil);
let completed = false;
void (async () => {
try {
const snapshot = await options.read({
url: watch.url,
host: watch.host,
knownActivity: () => watch.callbacks.knownActivity?.(),
isObserved,
assertHostAvailable() {
const nowMs = now();
const resetAtMs = pausesByHost.get(watch.host)?.requestsUntil ?? 0;
if (resetAtMs > nowMs) {
throw new ChangeRequestRateLimitError({ host: watch.host, resetAtMs });
}
},
deferPollsUntil: (untilMs) => deferHost(watch.host, untilMs, false),
pauseHost: (untilMs) => deferHost(watch.host, untilMs, true),
});
if (!isObserved()) return;
watch.consecutiveErrors = 0;
await watch.callbacks.snapshot(snapshot);
if (!isObserved()) return;
const nowMs = now();
const pause = pausesByHost.get(watch.host);
if (pause && pause.requestsUntil <= nowMs) pause.requestsUntil = 0;
watch.nextDueAt = Math.max(nowMs + pollIntervalMs, hostPauseUntil(watch.host, nowMs));
completed = true;
} catch (error) {
if (!isObserved()) return;
options.onError?.(error, watch.host);
const nowMs = now();
if (error instanceof ChangeRequestRateLimitError) {
deferHost(watch.host, error.resetAtMs, true);
watch.nextDueAt = Math.max(nowMs + pollIntervalMs, error.resetAtMs);
} else {
watch.consecutiveErrors += 1;
const backoff = Math.min(
pollIntervalMs * 2 ** (watch.consecutiveErrors - 1),
maxErrorBackoffMs,
);
watch.nextDueAt = nowMs + backoff;
}
watch.callbacks.error(error);
} finally {
// Rotate after a snapshot or a recovery attempt so a watch that
// keeps failing cannot take every turn after a quota reset.
if ((completed || recovering) && isObserved()) {
watches.delete(watch.url);
watches.set(watch.url, watch);
}
watch.inFlight = false;
const remaining = (inFlightByHost.get(watch.host) ?? 1) - 1;
if (remaining > 0) inFlightByHost.set(watch.host, remaining);
else inFlightByHost.delete(watch.host);
if (!disposed) {
// Immediately admit any queued due watch on this host, then re-arm timer.
drainDueWatches();
}
}
})();
}
return {
observe(url, callbacks) {
if (disposed) {
queueMicrotask(() => callbacks.error(new Error("Change request poller is disposed")));
return () => {};
}
const host = options.hostOf(url);
const nowMs = now();
const watch: WatchedEntry = {
url,
host,
callbacks,
nextDueAt: nowMs + initialDelayMs,
consecutiveErrors: 0,
inFlight: false,
};
watches.set(url, watch);
const pauseUntil = hostPauseUntil(host, nowMs);
if (pauseUntil > nowMs) {
queueMicrotask(() => {
if (!disposed && watches.get(url) === watch) {
callbacks.error(new ChangeRequestRateLimitError({ host, resetAtMs: pauseUntil }));
}
});
}
armTimer();
return () => {
if (watches.get(url) === watch) {
watches.delete(url);
armTimer();
}
};
},
dispose() {
disposed = true;
clearTimer();
watches.clear();
inFlightByHost.clear();
pausesByHost.clear();
},
};
}
@@ -0,0 +1,120 @@
import { describe, expect, it, vi } from "vitest";
import { createChangeRequestRouter } from "./change-request-router.js";
import type { ChangeRequestSource } from "./change-request-source.js";
import { createForgeResolver } from "./forge-resolver.js";
import type { ForgeService } from "./forge-service.js";
function createFakeSource(
forge: string,
canonicalize: (url: string) => string,
): ChangeRequestSource {
return {
resolve: canonicalize,
describe: (url) => `${forge}:${url}`,
observe: () => () => {},
};
}
function createFakeForgeService(changeRequests?: ChangeRequestSource): ForgeService {
return {
...(changeRequests ? { changeRequests } : {}),
invalidate() {},
} as unknown as ForgeService;
}
describe("createChangeRequestRouter", () => {
it("routes cloud hosts without probing and delegates canonicalization to the matched forge", async () => {
const probeForge = vi.fn(async () => {
throw new Error("cloud host must not trigger a probe");
});
const githubSource = createFakeSource(
"github",
(url) => `https://github.com/canonical/${new URL(url).pathname.split("/").at(-1)}`,
);
const gitlabSource = createFakeSource(
"gitlab",
(url) => `https://gitlab.com/canonical/${new URL(url).pathname.split("/").at(-1)}`,
);
const resolver = createForgeResolver({
probeForge,
createService: (forge) => {
if (forge === "github") return createFakeForgeService(githubSource);
if (forge === "gitlab") return createFakeForgeService(gitlabSource);
return null;
},
});
const router = createChangeRequestRouter({ forgeResolver: resolver });
await expect(router.resolve("https://GitHub.com/Org/Repo/pull/7")).resolves.toEqual({
forge: "github",
url: "https://github.com/canonical/7",
});
await expect(
router.resolve("https://gitlab.com/org/sub/repo/-/merge_requests/12"),
).resolves.toEqual({
forge: "gitlab",
url: "https://gitlab.com/canonical/12",
});
expect(probeForge).not.toHaveBeenCalled();
expect(router.source("github")).toBe(githubSource);
expect(router.source("gitlab")).toBe(gitlabSource);
});
it("probes self-hosted hosts before parsing the URL path", async () => {
const probeForge = vi.fn(async (host: string) =>
host === "git.corp.internal" ? "gitlab" : null,
);
const gitlabResolve = vi.fn(() => "https://git.corp.internal/team/app/-/merge_requests/9");
const githubResolve = vi.fn(() => {
throw new Error("github must not parse a gitlab host");
});
const resolver = createForgeResolver({
probeForge,
createService: (forge) => {
if (forge === "github")
return createFakeForgeService(createFakeSource("github", githubResolve));
if (forge === "gitlab")
return createFakeForgeService(createFakeSource("gitlab", gitlabResolve));
return null;
},
});
const router = createChangeRequestRouter({ forgeResolver: resolver });
await expect(
router.resolve("https://git.corp.internal/team/app/-/merge_requests/9"),
).resolves.toEqual({
forge: "gitlab",
url: "https://git.corp.internal/team/app/-/merge_requests/9",
});
expect(probeForge).toHaveBeenCalledWith("git.corp.internal");
expect(gitlabResolve).toHaveBeenCalledTimes(1);
expect(githubResolve).not.toHaveBeenCalled();
});
it("rejects unrecognized hosts, credentials, non-http schemes, and forges without watch support", async () => {
const resolver = createForgeResolver({
probeForge: async () => null,
createService: (forge) => {
if (forge === "gitea") return createFakeForgeService();
return null;
},
});
const router = createChangeRequestRouter({ forgeResolver: resolver });
await expect(router.resolve("not a url")).rejects.toThrow(/change request URL/i);
await expect(router.resolve("ftp://github.com/org/repo/pull/1")).rejects.toThrow(
/change request URL/i,
);
await expect(router.resolve("https://user:pass@github.com/org/repo/pull/1")).rejects.toThrow(
/change request URL/i,
);
await expect(router.resolve("https://unknown.example.com/org/repo/pull/1")).rejects.toThrow(
/unknown\.example\.com/,
);
await expect(router.resolve("https://gitea.com/org/repo/pulls/1")).rejects.toThrow(
/not supported.*gitea/i,
);
expect(router.source("gitea")).toBeNull();
expect(router.source("unknown")).toBeNull();
});
});
@@ -0,0 +1,80 @@
import { normalizeHost } from "@getpaseo/protocol/git-remote";
import type { ChangeRequestSource } from "./change-request-source.js";
import type { ForgeResolver } from "./forge-resolver.js";
export interface ResolvedChangeRequest {
forge: string;
url: string;
}
export interface ChangeRequestRouter {
/** Route a user-supplied URL host-first through registered forges and canonicalize it. */
resolve(url: string): Promise<ResolvedChangeRequest>;
/** Return the watch source for a known forge id without probing the network. */
source(forge: string): ChangeRequestSource | null;
}
export interface CreateChangeRequestRouterOptions {
forgeResolver: Pick<ForgeResolver, "resolveHost" | "getService">;
}
function extractUrlHost(input: string): { trimmed: string; host: string; authority: string } {
const trimmed = input.trim();
if (!trimmed || /\s/.test(trimmed)) {
throw new Error("Enter a supported change request URL.");
}
let parsed: URL;
try {
parsed = new URL(trimmed);
} catch {
throw new Error("Enter a supported change request URL.");
}
if (
(parsed.protocol !== "https:" && parsed.protocol !== "http:") ||
parsed.username ||
parsed.password
) {
throw new Error("Enter a supported change request URL.");
}
const host = normalizeHost(parsed.hostname);
if (!host) {
throw new Error("Enter a supported change request URL.");
}
return { trimmed, host, authority: parsed.port ? `${host}:${parsed.port}` : host };
}
/**
* Host-first router for change request watches. Resolves the target forge from
* the URL host via ForgeResolver (cloud match first, then cached CLI auth
* probe) before delegating path parsing and canonicalization to that forge's
* ChangeRequestSource.
*/
export function createChangeRequestRouter({
forgeResolver,
}: CreateChangeRequestRouterOptions): ChangeRequestRouter {
return {
async resolve(input: string): Promise<ResolvedChangeRequest> {
const { trimmed, host, authority } = extractUrlHost(input);
const resolution =
(await forgeResolver.resolveHost(authority)) ??
(authority === host ? null : await forgeResolver.resolveHost(host));
if (!resolution) {
throw new Error(
`Could not recognize a supported forge for host ${host}. Authenticate the forge CLI for this host first.`,
);
}
const source = resolution.service.changeRequests;
if (!source) {
throw new Error(`Change request watches are not supported for ${resolution.forge} yet.`);
}
return {
forge: resolution.forge,
url: source.resolve(trimmed),
};
},
source(forge: string): ChangeRequestSource | null {
return forgeResolver.getService(forge)?.changeRequests ?? null;
},
};
}
@@ -17,8 +17,9 @@ const changeRequestSnapshotSchema = changeRequestStatusSchema.extend({
activity: z.array(
z.object({
id: z.string(),
kind: z.enum(["comment", "inline comment", "review"]),
kind: z.enum(["comment", "inline comment", "review", "approval"]),
url: z.string(),
message: z.string().optional(),
}),
),
});
@@ -373,4 +373,40 @@ describe("createForgeResolver", () => {
expect(b).toMatchObject({ forge: "gitlab", host: "git.acme.internal" });
expect(probeForge).toHaveBeenCalledTimes(1);
});
it("resolves cloud and probed hosts directly via resolveHost and shares service instances", async () => {
const probeForge = vi.fn(async (host: string) =>
host === "git.acme.internal" ? "gitlab" : null,
);
const created: string[] = [];
const disposed: string[] = [];
const resolver = createForgeResolver({
probeForge,
createService: (forge) => {
created.push(forge);
const base = createForgeService(forge);
if (!base) return null;
return {
...base,
dispose: () => {
disposed.push(forge);
},
};
},
});
const cloud = await resolver.resolveHost("GitLab.com.");
expect(cloud).toMatchObject({ forge: "gitlab", host: "gitlab.com" });
expect(probeForge).not.toHaveBeenCalled();
const selfHosted = await resolver.resolveHost("GIT.ACME.INTERNAL");
expect(selfHosted).toMatchObject({ forge: "gitlab", host: "git.acme.internal" });
expect(selfHosted?.service).toBe(cloud?.service);
expect(probeForge).toHaveBeenCalledTimes(1);
expect(resolver.getService("gitlab")).toBe(cloud?.service);
expect(created).toEqual(["gitlab"]);
resolver.dispose();
expect(disposed).toEqual(["gitlab"]);
});
});
+60 -11
View File
@@ -1,5 +1,9 @@
import { LRUCache } from "lru-cache";
import { parseGitRemoteLocation, type GitRemoteLocation } from "@getpaseo/protocol/git-remote";
import {
normalizeHost,
parseGitRemoteLocation,
type GitRemoteLocation,
} from "@getpaseo/protocol/git-remote";
import { resolveSshHostname, type SshHostnameResolver } from "../utils/ssh-hostname.js";
import { defaultResolveRemoteUrl } from "./forge-cli-command.js";
import type { ForgeService } from "./forge-service.js";
@@ -24,6 +28,7 @@ export type ForgeHostProbe = (host: string) => Promise<string | null>;
export interface CreateForgeResolverOptions {
resolveRemoteUrl?: (cwd: string) => Promise<string | null>;
createService?: (forge: string) => ForgeService | null;
matchHost?: (host: string) => string | null;
probeForge?: ForgeHostProbe;
resolveSshHostname?: SshHostnameResolver;
now?: () => number;
@@ -36,12 +41,18 @@ export interface ForgeResolver {
resolveFromRemoteUrl(remoteUrl: string | null): ForgeResolution | null;
/** Resolve from a known origin remote URL, running the per-host probe when needed. */
resolveFromRemoteUrlAsync(remoteUrl: string | null): Promise<ForgeResolution | null>;
/** Resolve a forge directly by hostname (cloud match first, then cached async probe). */
resolveHost(host: string): Promise<ForgeResolution | null>;
/** Return the shared adapter instance for a known forge id without probing the network. */
getService(forge: string): ForgeService | null;
/**
* Invalidate every cached adapter's state for a cwd. Routed through the
* resolver so invalidation hits the same adapter instance the poller reads,
* regardless of which forge backs the workspace.
*/
invalidate(cwd: string): void;
/** Dispose all instantiated forge adapters owned by this resolver. */
dispose(): void;
}
// A positive probe (host IS a known forge) is cached permanently; a negative one
@@ -64,6 +75,7 @@ export function forgeForHost(host: string): string | null {
export function createForgeResolver(options: CreateForgeResolverOptions = {}): ForgeResolver {
const resolveRemoteUrl = options.resolveRemoteUrl ?? defaultResolveRemoteUrl;
const create = options.createService ?? createForgeService;
const matchHost = options.matchHost ?? forgeForHost;
const probeForge = options.probeForge ?? probeRegisteredForgeHost;
const resolveSsh = options.resolveSshHostname ?? resolveSshHostname;
const now = options.now ?? Date.now;
@@ -110,22 +122,34 @@ export function createForgeResolver(options: CreateForgeResolverOptions = {}): F
if (!entry) {
return undefined;
}
if (entry.expiresAt !== null && Date.now() >= entry.expiresAt) {
if (entry.expiresAt !== null && now() >= entry.expiresAt) {
probedForgeByHost.delete(host);
return undefined;
}
return entry.forge;
}
function buildResolution(forge: string, host: string): ForgeResolution | null {
let service = services.get(forge);
function getService(forge: string): ForgeService | null {
const normalized = forge.trim().toLowerCase();
if (!normalized) {
return null;
}
let service = services.get(normalized);
if (!service) {
const created = create(forge);
const created = create(normalized);
if (!created) {
return null;
}
service = created;
services.set(forge, service);
services.set(normalized, service);
}
return service;
}
function buildResolution(forge: string, host: string): ForgeResolution | null {
const service = getService(forge);
if (!service) {
return null;
}
return { forge, host, service };
}
@@ -151,7 +175,7 @@ export function createForgeResolver(options: CreateForgeResolverOptions = {}): F
}
probedForgeByHost.set(host, {
forge: probed,
expiresAt: probed === null ? Date.now() + NEGATIVE_PROBE_TTL_MS : null,
expiresAt: probed === null ? now() + NEGATIVE_PROBE_TTL_MS : null,
});
return probed;
} finally {
@@ -170,13 +194,29 @@ export function createForgeResolver(options: CreateForgeResolverOptions = {}): F
if (!host) {
return null;
}
const forge = forgeForHost(host) ?? readFreshProbe(host) ?? null;
const forge = matchHost(host) ?? readFreshProbe(host) ?? null;
if (!forge) {
return null;
}
return buildResolution(forge, host);
}
async function resolveHost(host: string): Promise<ForgeResolution | null> {
const normalized = normalizeHost(host);
if (!normalized) {
return null;
}
const directForge = matchHost(normalized);
if (directForge) {
return buildResolution(directForge, normalized);
}
const probed = await probeHostForge(normalized);
if (!probed) {
return null;
}
return buildResolution(probed, normalized);
}
async function resolveFromRemoteUrlAsync(
remoteUrl: string | null,
): Promise<ForgeResolution | null> {
@@ -187,7 +227,7 @@ export function createForgeResolver(options: CreateForgeResolverOptions = {}): F
if (!location) {
return null;
}
const directForge = forgeForHost(location.host);
const directForge = matchHost(location.host);
if (directForge) {
return buildResolution(directForge, location.host);
}
@@ -215,7 +255,7 @@ export function createForgeResolver(options: CreateForgeResolverOptions = {}): F
}
probedForgeByHost.set(aliasHost, {
forge,
expiresAt: forge === null ? Date.now() + NEGATIVE_PROBE_TTL_MS : null,
expiresAt: forge === null ? now() + NEGATIVE_PROBE_TTL_MS : null,
});
}
@@ -231,7 +271,7 @@ export function createForgeResolver(options: CreateForgeResolverOptions = {}): F
return { host: location.host };
}
const resolvedForge = forgeForHost(resolvedHost);
const resolvedForge = matchHost(resolvedHost);
if (resolvedForge) {
return { host: resolvedHost, forge: resolvedForge };
}
@@ -246,10 +286,19 @@ export function createForgeResolver(options: CreateForgeResolverOptions = {}): F
}
}
function dispose(): void {
for (const service of services.values()) {
service.dispose?.();
}
}
return {
resolveFromRemoteUrl,
resolveFromRemoteUrlAsync,
resolveHost,
getService,
invalidate,
dispose,
async resolve(cwd: string): Promise<ForgeResolution | null> {
return resolveFromRemoteUrlAsync(await resolveRemoteUrlCached(cwd));
},
@@ -1,4 +1,5 @@
import type { ForgeSearchKind } from "@getpaseo/protocol/messages";
import type { ChangeRequestSource } from "./change-request-source.js";
export type ForgeSearchRequestKind = ForgeSearchKind | "github-issue" | "github-pr" | "pr";
@@ -533,6 +534,8 @@ export interface ForgeService {
onError?: (error: unknown) => void;
},
): { unsubscribe: () => void };
/** Exact-URL change request observation adapter for watches, when supported by the forge. */
changeRequests?: ChangeRequestSource;
invalidate(options: { cwd: string }): void;
dispose?(): void;
}
File diff suppressed because it is too large Load Diff
@@ -0,0 +1,936 @@
import pLimit from "p-limit";
import { z } from "zod";
import { normalizeHost } from "@getpaseo/protocol/git-remote";
import {
ChangeRequestRateLimitError,
createPerHostChangeRequestPoller,
type PerHostReadContext,
parseCliHttpResponse,
parseRetryAfterMs,
} from "./change-request-poller.js";
import type { ChangeRequestSnapshot, ChangeRequestSource } from "./change-request-source.js";
import {
findTeaLoginNameForBaseUrl,
getGiteaActionTaskName,
GITEA_ACTION_MAX_PAGES,
GITEA_ACTION_PAGE_LIMIT,
GiteaActionsListResponseSchema,
GiteaCombinedCommitStatusSchema,
latestGiteaActionTasksByWorkflow,
parseGiteaActionTasks,
type GiteaActionTask,
type GiteaCommitStatus,
} from "./gitea-checks.js";
const GITEA_CLOUD_HOSTS = new Set(["gitea.com", "codeberg.org"]);
const GITEA_PR_TABS = new Set(["commits", "files", "checks"]);
const GITEA_PAGE_SIZE = GITEA_ACTION_PAGE_LIMIT;
const GITEA_REVIEW_COMMENT_CONCURRENCY = 3;
const GITEA_REVIEW_COMMENTS_TTL_MS = 5 * 60_000;
const GITEA_ACTION_RUN_LOOKUP_LIMIT = 5;
const checkUrlSchema = z.url({ protocol: /^https?$/ });
const giteaWatchPrSchema = z
.object({
number: z.number(),
state: z.string(),
merged: z.boolean().optional(),
merged_at: z.string().nullable().optional(),
html_url: z.string().optional(),
head: z
.object({
sha: z.string(),
})
.passthrough(),
})
.passthrough();
const giteaIssueCommentSchema = z
.object({
id: z.number(),
html_url: z.string().optional(),
type: z.string().optional(),
})
.passthrough();
const giteaReviewSchema = z
.object({
id: z.number(),
state: z.string(),
comments_count: z.number().optional().default(0),
submitted_at: z.string().nullable().optional(),
updated_at: z.string().nullable().optional(),
html_url: z.string().optional(),
})
.passthrough();
const giteaReviewCommentSchema = z
.object({
id: z.number(),
html_url: z.string().optional(),
})
.passthrough();
const giteaActionJobSchema = z.object({
id: z.number(),
name: z.string(),
status: z.string(),
conclusion: z.string().nullable().optional(),
html_url: z.string().nullable().optional(),
});
const giteaActionJobsPageSchema = z.union([
z.object({
jobs: z
.array(giteaActionJobSchema)
.nullable()
.transform((jobs) => jobs ?? []),
total_count: z.number(),
}),
// Forgejo returns the complete job list as an array.
z.array(giteaActionJobSchema),
]);
type GiteaActionJob = z.infer<typeof giteaActionJobSchema>;
type GiteaWatchPr = z.infer<typeof giteaWatchPrSchema>;
type GiteaReview = z.infer<typeof giteaReviewSchema>;
interface GiteaPullRequestIdentity {
baseUrl: string;
displayBase: string | null;
owner: string;
repo: string;
number: number;
}
function invalidGiteaUrl(): never {
throw new Error("Enter a Gitea, Forgejo, or Codeberg pull request URL.");
}
function parseGiteaUrlOrigin(input: string): {
protocol: "http:" | "https:";
host: string;
port: string;
hostWithPort: string;
pathname: string;
} {
const trimmed = input.trim();
if (!trimmed || /\s/.test(trimmed)) invalidGiteaUrl();
let parsed: URL;
try {
parsed = new URL(trimmed);
} catch {
invalidGiteaUrl();
}
const protocol = parsed.protocol.toLowerCase();
if ((protocol !== "https:" && protocol !== "http:") || parsed.username || parsed.password) {
invalidGiteaUrl();
}
const host = normalizeHost(parsed.hostname);
if (!host || (GITEA_CLOUD_HOSTS.has(host) && protocol !== "https:")) {
invalidGiteaUrl();
}
return {
protocol: protocol as "http:" | "https:",
host,
port: parsed.port,
hostWithPort: parsed.port ? `${host}:${parsed.port}` : host,
pathname: parsed.pathname,
};
}
function decodeRepoSegment(raw: string): string {
let decoded: string;
try {
decoded = decodeURIComponent(raw);
} catch {
invalidGiteaUrl();
}
if (
!decoded ||
decoded === "." ||
decoded === ".." ||
decoded.includes("/") ||
decoded.includes("\\")
) {
invalidGiteaUrl();
}
return decoded;
}
function parseGiteaPullRequestUrl(input: string): GiteaPullRequestIdentity {
const origin = parseGiteaUrlOrigin(input);
const segments = origin.pathname.split("/").filter(Boolean);
if (
segments.length >= 5 &&
GITEA_PR_TABS.has(segments.at(-1)!.toLowerCase()) &&
/^\d+$/.test(segments.at(-2)!)
) {
segments.pop();
}
const rawNumber = segments.pop();
const number = Number(rawNumber);
const resource = segments.pop();
const repo = segments.pop();
const owner = segments.pop();
if (
resource?.toLowerCase() !== "pulls" ||
!owner ||
!repo ||
!rawNumber ||
!/^\d+$/.test(rawNumber) ||
!Number.isInteger(number) ||
number < 1 ||
number > 2_147_483_647
) {
invalidGiteaUrl();
}
const path = segments.length ? `/${segments.join("/")}` : "";
const displayBase =
!path && !origin.port && GITEA_CLOUD_HOSTS.has(origin.host)
? null
: `${origin.hostWithPort}${path}`;
return {
baseUrl: `${origin.protocol}//${origin.hostWithPort}${path}`,
displayBase,
owner: decodeRepoSegment(owner),
repo: decodeRepoSegment(repo),
number,
};
}
export function resolveGiteaChangeRequest(input: string): string {
const { baseUrl, owner, repo, number } = parseGiteaPullRequestUrl(input);
return `${baseUrl}/${owner.toLowerCase()}/${repo.toLowerCase()}/pulls/${number}`;
}
export function describeGiteaChangeRequest(url: string): string {
const { displayBase, owner, repo, number } = parseGiteaPullRequestUrl(url);
const project = displayBase ? `${displayBase}/${owner}/${repo}` : `${owner}/${repo}`;
return `${project} #${number}`;
}
function mapGiteaPrState(pr: GiteaWatchPr): ChangeRequestSnapshot["state"] {
if (pr.merged === true || pr.merged_at != null) return "merged";
const normalized = pr.state.toLowerCase();
if (normalized === "open") return "open";
if (normalized === "merged") return "merged";
return "closed";
}
function mapCommitStatusToWatchState(
status: string,
): ChangeRequestSnapshot["checks"][number]["state"] {
switch (status.toLowerCase()) {
case "success":
return "passed";
case "failure":
case "error":
case "warning":
return "failed";
case "pending":
case "running":
return "pending";
default:
return "neutral";
}
}
function isCanceledActionStatus(status: GiteaCommitStatus): boolean {
// Actions writes a generic failure state on cancellation, with a distinct
// description in the native job's commit status.
const description = status.description ?? "";
return description === "Has been cancelled" || description.startsWith("Canceled after ");
}
function mapActionTaskToWatchState(
status: string,
): ChangeRequestSnapshot["checks"][number]["state"] {
switch (status.toLowerCase()) {
case "success":
return "passed";
case "failure":
case "failed":
case "error":
return "failed";
case "cancelled":
case "canceled":
case "skipped":
return "neutral";
default:
return "pending";
}
}
function computeAggregateChecksState(
checks: ChangeRequestSnapshot["checks"],
): ChangeRequestSnapshot["checksState"] {
if (checks.length === 0) return "neutral";
if (checks.some((check) => check.state === "failed")) return "failed";
if (checks.some((check) => check.state === "pending")) return "pending";
if (checks.some((check) => check.state === "passed")) return "passed";
return "neutral";
}
function nativeActionUrl(value: string | null | undefined, origin: string) {
if (!value) return null;
try {
const url = new URL(value, origin);
if (url.origin !== origin) return null;
const match = /^(.*\/actions\/runs\/(\d+))(\/jobs\/\d+)?\/?$/.exec(url.pathname);
if (!match) return null;
const [, run, runId, job] = match;
return { run: run!, runId: runId!, jobUrl: job ? `${origin}${run}${job}` : null };
} catch {
return null;
}
}
function combineWatchChecks(
commitStatuses: GiteaCommitStatus[],
actionTasks: GiteaActionTask[],
jobsByRun: ReadonlyMap<string, GiteaActionJob[]>,
origin: string,
): ChangeRequestSnapshot["checks"] {
const checks: ChangeRequestSnapshot["checks"] = [];
const actionJobs = [...jobsByRun.values()].flat();
const coveredJobUrls = new Set(
actionJobs.map((job) => nativeActionUrl(job.html_url, origin)?.jobUrl),
);
for (const status of commitStatuses) {
const jobUrl = nativeActionUrl(status.target_url, origin)?.jobUrl;
if (jobUrl && coveredJobUrls.has(jobUrl)) continue;
const url = checkUrlSchema.safeParse(status.target_url).data;
checks.push({
id: `status:${status.id}`,
name: status.context || `status-${status.id}`,
state:
jobUrl && isCanceledActionStatus(status)
? "neutral"
: mapCommitStatusToWatchState(status.status),
...(url ? { url } : {}),
});
}
for (const job of actionJobs) {
const url = checkUrlSchema.safeParse(job.html_url).data;
checks.push({
id: `action-job:${job.id}`,
name: job.name,
state: mapActionTaskToWatchState(job.conclusion || job.status),
...(url ? { url } : {}),
});
}
const seenTaskIds = new Set<number>();
for (const task of actionTasks) {
if (seenTaskIds.has(task.id)) continue;
const address = nativeActionUrl(task.url, origin);
if (address && jobsByRun.has(address.run)) continue;
seenTaskIds.add(task.id);
const url = checkUrlSchema.safeParse(task.url).data;
checks.push({
id: `action:${task.id}`,
name: getGiteaActionTaskName(task),
state: mapActionTaskToWatchState(task.status),
...(url ? { url } : {}),
});
}
return checks;
}
function hasNextLinkHeader(headers: ReadonlyMap<string, string>): boolean {
const link = headers.get("link");
return link ? /rel=["']?next["']?/i.test(link) : false;
}
function parseTotalCountHeader(headers: ReadonlyMap<string, string>): number | null {
const raw = headers.get("x-total-count");
if (!raw) return null;
const parsed = Number(raw);
return Number.isInteger(parsed) && parsed >= 0 ? parsed : null;
}
function isSubmittedGiteaReview(review: GiteaReview): boolean {
const state = review.state.trim().toUpperCase();
return state !== "PENDING" && state !== "REQUEST_REVIEW";
}
function parseTeaHttpStreams(
stdout: string,
stderr: string,
): {
status: number | null;
headers: Map<string, string>;
body: string;
} {
const fromStdout = parseCliHttpResponse(stdout);
if (fromStdout.status !== null) {
return fromStdout;
}
const fromStderr = parseCliHttpResponse(stderr);
if (fromStderr.status !== null) {
return { status: fromStderr.status, headers: fromStderr.headers, body: stdout.trim() };
}
return { status: null, headers: new Map(), body: stdout.trim() };
}
class TeaHttpStatusError extends Error {
readonly status: number;
constructor(status: number, message: string) {
super(message);
this.name = "TeaHttpStatusError";
this.status = status;
}
}
function isOptionalEndpointStatus(error: unknown): boolean {
return (
error instanceof TeaHttpStatusError &&
(error.status === 403 || error.status === 404 || error.status === 501)
);
}
type TeaApiGet = <T>(
endpoint: string,
schema: z.ZodType<T>,
) => Promise<{ data: T; headers: ReadonlyMap<string, string> }>;
interface TeaPollApi {
get: TeaApiGet;
all<T extends readonly unknown[]>(
reads: T,
): Promise<{ -readonly [Key in keyof T]: Awaited<T[Key]> }>;
}
interface CachedReviewComments {
count: number;
fetchedAt: number;
items: ChangeRequestSnapshot["activity"];
}
export interface CreateGiteaChangeRequestSourceOptions {
runCommand(
args: string[],
options: { cwd: string; envOverlay?: Record<string, string> },
): Promise<{ stdout: string; stderr: string }>;
createAuthError(stderr: string): Error;
createCommandError(params: {
args: string[];
cwd: string;
exitCode: number | null;
stderr: string;
stdout?: string;
}): Error;
now?: () => number;
pollIntervalMs?: number;
initialDelayMs?: number;
}
export function createGiteaChangeRequestSource(
options: CreateGiteaChangeRequestSourceOptions,
): ChangeRequestSource & { dispose(): void } {
const now = options.now ?? Date.now;
const cachedReviewCommentsByUrl = new Map<string, Map<number, CachedReviewComments>>();
const reviewCommentLimit = pLimit(GITEA_REVIEW_COMMENT_CONCURRENCY);
async function resolveLogin(baseUrl: string): Promise<string> {
const result = await options.runCommand(["login", "list", "-o", "json"], {
cwd: process.cwd(),
});
const loginName = findTeaLoginNameForBaseUrl(result.stdout, baseUrl);
if (!loginName) {
throw options.createAuthError(`No tea login configured for ${baseUrl}`);
}
return loginName;
}
function parseJsonBody<T>(params: {
args: string[];
cwd: string;
body: string;
schema: z.ZodType<T>;
}): T {
let data: unknown;
try {
data = JSON.parse(params.body);
} catch {
throw options.createCommandError({
args: params.args,
cwd: params.cwd,
exitCode: null,
stderr: `tea did not return valid JSON (${params.body.length} bytes)`,
});
}
const parsed = params.schema.safeParse(data);
if (!parsed.success) {
throw options.createCommandError({
args: params.args,
cwd: params.cwd,
exitCode: null,
stderr: `tea JSON did not match the expected schema: ${parsed.error.message}`,
});
}
return parsed.data;
}
function bindTeaApi(context: PerHostReadContext, loginName: string): TeaPollApi {
let active = true;
const get: TeaApiGet = async (endpoint, schema) => {
if (!active || !context.isObserved()) throw new Error("Change request observation ended");
context.assertHostAvailable();
const args = ["api", "--login", loginName, "-i", endpoint];
const cwd = process.cwd();
const result = await options.runCommand(args, { cwd });
const parsed = parseTeaHttpStreams(result.stdout, result.stderr);
const nowMs = now();
// tea api can exit 0 on an HTTP failure, so always check the status line.
if (parsed.status === null) {
throw options.createCommandError({
args,
cwd,
exitCode: 0,
stderr: "tea api -i did not return an HTTP status line",
stdout: result.stdout,
});
}
if (parsed.status === 429) {
const resetAtMs = parseRetryAfterMs(parsed.headers, nowMs, {
forceOnMissing: true,
defaultPauseMs: 60_000,
})!;
context.pauseHost(resetAtMs);
throw new ChangeRequestRateLimitError({ host: context.host, resetAtMs });
}
if (parsed.status === 401) {
throw options.createAuthError(parsed.body || "401 Unauthorized");
}
if (parsed.status < 200 || parsed.status >= 300) {
throw new TeaHttpStatusError(
parsed.status,
`Gitea API returned HTTP ${parsed.status} for ${endpoint}: ${parsed.body}`.trim(),
);
}
const proactivePause = parseRetryAfterMs(parsed.headers, nowMs);
if (proactivePause !== null) context.deferPollsUntil(proactivePause);
const data = parseJsonBody({ args, cwd, body: parsed.body, schema });
return { data, headers: parsed.headers };
};
return {
get,
all(reads) {
return Promise.all(reads).catch(async (error: unknown) => {
// Stop admitting reads from this poll and hold its host slot until
// requests already sent (including late rate limits) settle.
active = false;
await Promise.allSettled(reads);
throw error;
});
},
};
}
async function teaApiGetAllPages<T>(params: {
get: TeaApiGet;
endpoint: string;
itemSchema: z.ZodType<T>;
}): Promise<T[]> {
const items: T[] = [];
const schema = z.array(params.itemSchema);
let minPageSize = 1;
for (let page = 1; ; page += 1) {
const sep = params.endpoint.includes("?") ? "&" : "?";
const { data, headers } = await params.get(
`${params.endpoint}${sep}page=${page}&limit=${GITEA_PAGE_SIZE}`,
schema,
);
items.push(...data);
if (headers.has("link")) {
if (hasNextLinkHeader(headers)) continue;
break;
}
const totalCount = parseTotalCountHeader(headers);
if (totalCount !== null) {
// Gitea can cap limit below the requested value and filter pending
// reviews after pagination. The largest page is a lower bound on
// the number of records advanced on every page.
minPageSize = Math.max(minPageSize, data.length);
if (page * minPageSize < totalCount) continue;
break;
}
if (data.length < GITEA_PAGE_SIZE) break;
}
return items;
}
async function readCommitStatuses(params: {
get: TeaApiGet;
repoPrefix: string;
headSha: string;
isObserved(): boolean;
}): Promise<{ statuses: GiteaCommitStatus[]; pagesRead: number }> {
const statuses: GiteaCommitStatus[] = [];
const seenIds = new Set<number>();
let page = 1;
let pagesRead = 0;
while (true) {
if (!params.isObserved()) return { statuses, pagesRead };
const response = await params.get(
`${params.repoPrefix}/commits/${encodeURIComponent(params.headSha)}/status?limit=${GITEA_PAGE_SIZE}&page=${page}`,
GiteaCombinedCommitStatusSchema,
);
pagesRead += 1;
const pageStatuses = response.data.statuses;
if (pageStatuses.length === 0) break;
for (const status of pageStatuses) {
if (seenIds.has(status.id)) {
throw new Error("Gitea commit status pages overlap. Retry the poll.");
}
seenIds.add(status.id);
statuses.push(status);
}
// Gitea sets body `total_count` to the current page length; the full total
// lives only in the `X-Total-Count` response header.
const headerTotal = parseTotalCountHeader(response.headers);
if (headerTotal !== null) {
if (statuses.length >= headerTotal) break;
page += 1;
continue;
}
if (hasNextLinkHeader(response.headers) || pageStatuses.length >= GITEA_PAGE_SIZE) {
page += 1;
continue;
}
break;
}
return { statuses, pagesRead };
}
async function readBoundedActionTasks(params: {
get: TeaApiGet;
repoPrefix: string;
isObserved(): boolean;
}): Promise<{ items: unknown[]; pagesRead: number }> {
const items: unknown[] = [];
let fetched = 0;
let pagesRead = 0;
for (let page = 1; page <= GITEA_ACTION_MAX_PAGES; page += 1) {
if (!params.isObserved()) return { items, pagesRead };
let response: { data: z.infer<typeof GiteaActionsListResponseSchema> };
try {
response = await params.get(
`${params.repoPrefix}/actions/tasks?limit=${GITEA_PAGE_SIZE}&page=${page}`,
GiteaActionsListResponseSchema,
);
} catch (error) {
if (page === 1 && isOptionalEndpointStatus(error)) {
return { items: [], pagesRead: 0 };
}
throw error;
}
pagesRead += 1;
const runs = response.data.workflow_runs;
if (runs.length === 0) break;
fetched += runs.length;
items.push(...runs);
if (response.data.total_count !== undefined && fetched >= response.data.total_count) break;
}
return { items, pagesRead };
}
async function readActionJobs(params: {
get: TeaApiGet;
origin: string;
repoPrefix: string;
tasks: GiteaActionTask[];
statuses: GiteaCommitStatus[];
}): Promise<Map<string, GiteaActionJob[]>> {
// Commit statuses identify a job URL. Tasks identify a run, so only a job
// list can establish coverage when both sources report the same run.
const statusRuns = new Set<string>();
for (const status of params.statuses) {
const address = nativeActionUrl(status.target_url, params.origin);
if (address?.jobUrl) statusRuns.add(address.run);
}
const runs = new Map<string, string>();
for (const task of params.tasks) {
const address = nativeActionUrl(task.url, params.origin);
if (address && statusRuns.has(address.run)) runs.set(address.run, address.runId);
}
const jobsByRun = new Map<string, GiteaActionJob[]>();
for (const [run, runId] of [...runs].slice(0, GITEA_ACTION_RUN_LOOKUP_LIMIT)) {
const endpoint = `${params.repoPrefix}/actions/runs/${runId}/jobs`;
const jobs = new Map<number, GiteaActionJob>();
for (let page = 1; page <= GITEA_ACTION_MAX_PAGES; page += 1) {
try {
const { data } = await params.get(
`${endpoint}?limit=${GITEA_PAGE_SIZE}&page=${page}`,
giteaActionJobsPageSchema,
);
const items = Array.isArray(data) ? data : data.jobs;
const totalCount = Array.isArray(data) ? data.length : data.total_count;
if (!items.length) break;
// The browser run number and API ID differ on some versions. Keep
// the original sources if any job belongs to another run.
if (items.some((job) => nativeActionUrl(job.html_url, params.origin)?.run !== run)) {
break;
}
for (const job of items) jobs.set(job.id, job);
if (jobs.size >= totalCount) {
jobsByRun.set(run, [...jobs.values()]);
break;
}
} catch (error) {
if (page === 1 && isOptionalEndpointStatus(error)) break;
throw error;
}
}
}
return jobsByRun;
}
async function readChecks(params: {
api: TeaPollApi;
origin: string;
repoPrefix: string;
prEndpoint: string;
headSha: string;
isObserved(): boolean;
}): Promise<ChangeRequestSnapshot["checks"]> {
const { get, all } = params.api;
const [statusResult, tasksResult] = await all([
readCommitStatuses({ ...params, get }),
readBoundedActionTasks({ ...params, get }),
]);
if (!params.isObserved()) {
throw new Error("Change request observation ended");
}
const matchingTasks = parseGiteaActionTasks(tasksResult.items).filter(
(task) => task.head_sha === params.headSha,
);
const latestTasks = latestGiteaActionTasksByWorkflow(matchingTasks);
const jobsByRun = await readActionJobs({
...params,
get,
tasks: latestTasks,
statuses: statusResult.statuses,
});
if (statusResult.pagesRead > 1 || tasksResult.pagesRead > 1 || jobsByRun.size > 0) {
const { data: recheck } = await get(params.prEndpoint, giteaWatchPrSchema);
if (recheck.head.sha !== params.headSha) {
throw new Error("The pull request head changed during pagination.");
}
}
return combineWatchChecks(statusResult.statuses, latestTasks, jobsByRun, params.origin);
}
async function readActivity(params: {
url: string;
api: TeaPollApi;
repoPrefix: string;
number: number;
prWebUrl: string;
terminal: boolean;
knownActivity(): ReadonlySet<string> | undefined;
isObserved(): boolean;
}): Promise<ChangeRequestSnapshot["activity"]> {
const { get, all } = params.api;
const [comments, reviews] = await all([
teaApiGetAllPages({
get,
endpoint: `${params.repoPrefix}/issues/${params.number}/comments`,
itemSchema: giteaIssueCommentSchema,
}),
teaApiGetAllPages({
get,
endpoint: `${params.repoPrefix}/pulls/${params.number}/reviews`,
itemSchema: giteaReviewSchema,
}),
]);
if (!params.isObserved()) {
throw new Error("Change request observation ended");
}
const activity: ChangeRequestSnapshot["activity"] = [];
for (const comment of comments) {
if (comment.type !== undefined && comment.type !== "comment") continue;
activity.push({
id: `comment:${comment.id}`,
kind: "comment",
url: comment.html_url || `${params.prWebUrl}#issuecomment-${comment.id}`,
});
}
const submittedReviews = reviews.filter(isSubmittedGiteaReview);
for (const review of submittedReviews) {
activity.push({
id: `review:${review.id}`,
kind: "review",
url: review.html_url || `${params.prWebUrl}#pullrequestreview-${review.id}`,
});
}
const known = params.knownActivity();
let reviewCache = cachedReviewCommentsByUrl.get(params.url);
if (!reviewCache) {
reviewCache = new Map<number, CachedReviewComments>();
cachedReviewCommentsByUrl.set(params.url, reviewCache);
}
const staleBefore = now() - GITEA_REVIEW_COMMENTS_TTL_MS;
const reviewsNeedingFetch = submittedReviews.filter((review) => {
if (review.comments_count <= 0) return false;
const cached = reviewCache.get(review.id);
if (
!params.terminal &&
cached &&
cached.fetchedAt > staleBefore &&
cached.count === review.comments_count &&
cached.items.every((item) => known?.has(item.id))
) {
return false;
}
return true;
});
// Gitea's review-comments endpoint returns all comments for a review in one
// response and ignores page/limit, so fetch it once without a pagination loop.
const fetchedGroups = await all(
reviewsNeedingFetch.map((review) =>
reviewCommentLimit(async () => {
if (!params.isObserved()) {
return { reviewId: review.id, count: review.comments_count, items: [] };
}
const { data: inlineComments } = await get(
`${params.repoPrefix}/pulls/${params.number}/reviews/${review.id}/comments`,
z.array(giteaReviewCommentSchema),
);
const items: ChangeRequestSnapshot["activity"] = inlineComments.map((comment) => ({
id: `inline:${comment.id}`,
kind: "inline comment",
url: comment.html_url || `${params.prWebUrl}#issuecomment-${comment.id}`,
}));
return { reviewId: review.id, count: review.comments_count, items };
}),
),
);
if (!params.isObserved()) {
throw new Error("Change request observation ended");
}
const fetchedAt = now();
for (const group of fetchedGroups) {
reviewCache.set(group.reviewId, { count: group.count, fetchedAt, items: group.items });
}
for (const review of submittedReviews) {
if (review.comments_count <= 0) continue;
const cached = reviewCache.get(review.id);
if (cached) {
activity.push(...cached.items);
}
}
return activity;
}
async function readPullRequest(context: PerHostReadContext): Promise<ChangeRequestSnapshot> {
const identity = parseGiteaPullRequestUrl(context.url);
const { baseUrl, owner, repo, number } = identity;
const loginName = await resolveLogin(baseUrl);
const api = bindTeaApi(context, loginName);
const repoPrefix = `repos/${encodeURIComponent(owner)}/${encodeURIComponent(repo)}`;
const prEndpoint = `${repoPrefix}/pulls/${number}`;
const { data: pr } = await api.get(prEndpoint, giteaWatchPrSchema);
if (!pr.head.sha) {
throw new Error(`Gitea pull request #${number} did not include a head commit SHA.`);
}
const prWebUrl = pr.html_url || context.url;
const address = parseGiteaPullRequestUrl(prWebUrl);
if (
address.baseUrl !== baseUrl ||
address.owner.toLowerCase() !== owner.toLowerCase() ||
address.repo.toLowerCase() !== repo.toLowerCase() ||
address.number !== number ||
pr.number !== number
) {
throw new Error("Tea returned a pull request that does not match the watch URL.");
}
const checks = await readChecks({
api,
origin: context.host,
repoPrefix,
prEndpoint,
headSha: pr.head.sha,
isObserved: context.isObserved,
});
const state = mapGiteaPrState(pr);
const activity = await readActivity({
url: context.url,
api,
repoPrefix,
number,
prWebUrl,
terminal: state !== "open",
knownActivity: context.knownActivity,
isObserved: context.isObserved,
});
return {
state,
headSha: pr.head.sha,
checksState: computeAggregateChecksState(checks),
checks,
reviewDecision: null,
activity,
};
}
const poller = createPerHostChangeRequestPoller({
hostOf: (url) => new URL(url).origin,
read: readPullRequest,
now,
pollIntervalMs: options.pollIntervalMs,
initialDelayMs: options.initialDelayMs,
});
return {
resolve: resolveGiteaChangeRequest,
describe: describeGiteaChangeRequest,
observe(url, callbacks) {
const release = poller.observe(url, callbacks);
return () => {
cachedReviewCommentsByUrl.delete(url);
release();
};
},
dispose() {
cachedReviewCommentsByUrl.clear();
poller.dispose();
},
};
}
@@ -0,0 +1,253 @@
import { z } from "zod";
import { normalizeHost } from "@getpaseo/protocol/git-remote";
// 50 is the page-size cap Gitea enforces on list endpoints; five pages bounds
// the sweep to the 250 most recent Actions tasks.
export const GITEA_ACTION_PAGE_LIMIT = 50;
export const GITEA_ACTION_MAX_PAGES = 5;
const GITEA_RELATIVE_URL_ORIGIN = "https://gitea.invalid";
export const GiteaLoginSchema = z
.object({
name: z.string().optional(),
url: z.string().optional(),
ssh_host: z.string().optional(),
})
.passthrough();
export const GiteaCommitStatusSchema = z
.object({
id: z.number(),
status: z.string(),
target_url: z.string().nullable().optional(),
description: z.string().nullable().optional(),
url: z.string().nullable().optional(),
context: z.string().optional().default(""),
creator: z.unknown().nullable().optional(),
})
.passthrough();
export const GiteaCombinedCommitStatusSchema = z
.object({
state: z.string().optional().default(""),
sha: z.string().optional(),
total_count: z.number().optional(),
statuses: z
.array(GiteaCommitStatusSchema)
.nullable()
.optional()
.transform((value) => value ?? []),
})
.passthrough();
export const GiteaActionTaskSchema = z
.object({
id: z.number(),
name: z.string().nullable().optional(),
head_branch: z.string().nullable().optional(),
head_sha: z.string(),
run_number: z.number().optional(),
event: z.string().nullable().optional(),
display_title: z.string().nullable().optional(),
status: z.string(),
need_approval: z.boolean().optional().default(false),
workflow_id: z.string().nullable().optional(),
url: z.string().nullable().optional(),
created_at: z.string().nullable().optional(),
run_started_at: z.string().nullable().optional(),
})
.passthrough();
// The item shape is validated per-task rather than as `z.array(GiteaActionTaskSchema)`
// so one malformed task (missing id/status/head_sha) drops only itself instead of
// throwing out the whole page and zeroing every Actions check for the PR.
export const GiteaActionsListResponseSchema = z
.object({
workflow_runs: z
.array(z.unknown())
.nullable()
.optional()
.transform((value) => value ?? []),
total_count: z.number().optional(),
})
.passthrough();
export type GiteaCommitStatus = z.infer<typeof GiteaCommitStatusSchema>;
export type GiteaCombinedCommitStatus = z.infer<typeof GiteaCombinedCommitStatusSchema>;
export type GiteaActionTask = z.infer<typeof GiteaActionTaskSchema>;
export function getGiteaActionTaskName(task: GiteaActionTask): string {
return task.name || task.display_title || task.workflow_id || `actions-${task.id}`;
}
export function getUrlOrigin(value: string | null | undefined): string | null {
if (!value) return null;
try {
return new URL(value).origin;
} catch {
return null;
}
}
export function getGiteaActionRunIdFromUrl(value: string | null | undefined): number | null {
if (!value) return null;
try {
const url = new URL(value, GITEA_RELATIVE_URL_ORIGIN);
const match = url.pathname.match(/\/actions\/runs\/(\d+)(?:\/jobs\/\d+)?\/?$/);
return match?.[1] ? Number.parseInt(match[1], 10) : null;
} catch {
return null;
}
}
function isNativeActionJobUrl(
targetUrl: string | null | undefined,
nativeOrigins: ReadonlySet<string>,
nativeRunIds: ReadonlySet<number>,
): boolean {
if (!targetUrl) return false;
try {
const url = new URL(targetUrl, GITEA_RELATIVE_URL_ORIGIN);
if (!/\/actions\/runs\/\d+\/jobs\/\d+\/?$/.test(url.pathname)) return false;
if (url.origin !== GITEA_RELATIVE_URL_ORIGIN && !nativeOrigins.has(url.origin)) return false;
const runId = getGiteaActionRunIdFromUrl(targetUrl);
return runId !== null && nativeRunIds.has(runId);
} catch {
return false;
}
}
// A "shadow" is the commit status Gitea synthesizes to mirror one of its own
// Actions jobs; keeping both would double-report every job. Detection is purely
// structural: Gitea always creates these statuses with a target_url of the form
// "<run link>/jobs/<job id>" (services/actions/commit_status.go upstream), so a
// status is a shadow exactly when its URL points at a job of a run we actually
// fetched from the Actions API. Anything else - external CI, URL-less statuses,
// contexts that merely look like "<workflow> / <job> (<event>)" - is kept.
export function isGiteaActionShadowStatus(
status: GiteaCommitStatus,
nativeOrigins: ReadonlySet<string>,
nativeRunIds: ReadonlySet<number>,
): boolean {
return isNativeActionJobUrl(status.target_url, nativeOrigins, nativeRunIds);
}
function getGiteaActionWorkflowIdentity(task: GiteaActionTask): string {
if (task.workflow_id) {
return `workflow\u0000${task.workflow_id}`;
}
// Instances that omit workflow_id (older Gitea/Forgejo payloads) still need
// reruns of the same job collapsed to the latest execution, so fall back to
// the job name before treating the task as its own group.
const name = task.name || task.display_title;
if (name) {
return `name\u0000${name}`;
}
return `task\u0000${getGiteaActionExecutionIdentity(task)}`;
}
function getGiteaActionExecutionIdentity(task: GiteaActionTask): string {
if (task.run_number !== undefined) return `run-number\u0000${task.run_number}`;
const runId = getGiteaActionRunIdFromUrl(task.url);
if (runId !== null) return `run-id\u0000${runId}`;
if (task.url) return `url\u0000${task.url}`;
return `task\u0000${task.id}`;
}
function parseGiteaActionTaskTime(task: GiteaActionTask): number {
const timestamp = task.created_at ?? task.run_started_at ?? null;
if (!timestamp) {
return 0;
}
const time = Date.parse(timestamp);
return Number.isNaN(time) ? 0 : time;
}
function compareGiteaActionTaskRecency(left: GiteaActionTask, right: GiteaActionTask): number {
const leftRunNumber = left.run_number ?? 0;
const rightRunNumber = right.run_number ?? 0;
if (leftRunNumber !== rightRunNumber) {
return leftRunNumber - rightRunNumber;
}
const leftTime = parseGiteaActionTaskTime(left);
const rightTime = parseGiteaActionTaskTime(right);
if (leftTime !== rightTime) {
return leftTime - rightTime;
}
return left.id - right.id;
}
export function parseGiteaActionTasks(rawTasks: unknown[]): GiteaActionTask[] {
const tasks: GiteaActionTask[] = [];
for (const raw of rawTasks) {
const parsed = GiteaActionTaskSchema.safeParse(raw);
if (parsed.success) {
tasks.push(parsed.data);
}
}
return tasks;
}
/**
* Keep all sibling tasks from the latest execution of each workflow.
* Per docs/forge-providers.md, ambiguous same-run tasks are preserved because
* display names are not stable job identities and `/actions/tasks` omits rerun
* attempt numbers.
*/
export function latestGiteaActionTasksByWorkflow(tasks: GiteaActionTask[]): GiteaActionTask[] {
const latestExecutions = new Map<string, GiteaActionTask>();
for (const task of tasks) {
const identity = getGiteaActionWorkflowIdentity(task);
const current = latestExecutions.get(identity);
if (!current || compareGiteaActionTaskRecency(current, task) < 0) {
latestExecutions.set(identity, task);
}
}
return tasks.filter((task) => {
const latest = latestExecutions.get(getGiteaActionWorkflowIdentity(task));
return (
latest !== undefined &&
getGiteaActionExecutionIdentity(task) === getGiteaActionExecutionIdentity(latest)
);
});
}
function parseTeaLogins(stdout: string): z.infer<typeof GiteaLoginSchema>[] {
try {
return z.array(GiteaLoginSchema).safeParse(JSON.parse(stdout)).data ?? [];
} catch {
return [];
}
}
export function findTeaLoginNameForBaseUrl(stdout: string, baseUrl: string): string | null {
const match = parseTeaLogins(stdout).find((login) => {
if (!login.name || !login.url) return false;
try {
const url = new URL(login.url);
return `${url.origin}${url.pathname.replace(/\/+$/, "")}` === baseUrl;
} catch {
return false;
}
});
return match?.name ?? null;
}
export function findTeaLoginNameForHost(stdout: string, host: string): string | null {
const targetHost = normalizeHost(host);
const match = parseTeaLogins(stdout).find((login) => {
const candidates = [login.ssh_host, login.name];
if (login.url) {
try {
candidates.push(new URL(login.url).hostname);
} catch {
// ignore malformed login url
}
}
return candidates.some((candidate) => candidate && normalizeHost(candidate) === targetHost);
});
return match?.name ?? null;
}
+44 -227
View File
@@ -61,6 +61,23 @@ import type {
SearchIssuesAndPrsOptions,
SearchResult,
} from "./forge-service.js";
import {
findTeaLoginNameForHost,
getGiteaActionRunIdFromUrl,
getGiteaActionTaskName,
getUrlOrigin,
GITEA_ACTION_MAX_PAGES,
GITEA_ACTION_PAGE_LIMIT,
GiteaActionsListResponseSchema,
GiteaCombinedCommitStatusSchema,
isGiteaActionShadowStatus,
latestGiteaActionTasksByWorkflow,
parseGiteaActionTasks,
type GiteaActionTask,
type GiteaCombinedCommitStatus,
type GiteaCommitStatus,
} from "./gitea-checks.js";
import { createGiteaChangeRequestSource } from "./gitea-change-requests.js";
import { isGiteaStatusFacts, type GiteaStatusFacts } from "./gitea-facts.js";
const TEA_ENV = {
@@ -77,10 +94,6 @@ const reviewCommentsLimit = pLimit(REVIEW_COMMENTS_FAN_OUT_CONCURRENCY);
// short cache, each poll re-derives the PR head SHA from scratch (branch name +
// PR lookup + PR view). The TTL keeps a new push visible within one poll cycle.
const CURRENT_PR_HEAD_SHA_CACHE_TTL_MS = 30_000;
// 50 is the page-size cap Gitea enforces on list endpoints; five pages bounds
// the sweep to the 250 most recent Actions tasks.
const GITEA_ACTION_PAGE_LIMIT = 50;
const GITEA_ACTION_MAX_PAGES = 5;
// PullRequestFlowAGit in forgejo models/issues/pull.go
const GITEA_PULL_REQUEST_FLOW_AGIT = 1;
@@ -142,6 +155,8 @@ export interface CreateGiteaServiceOptions {
resolveRemoteUrl?: (cwd: string) => Promise<string | null>;
resolveCurrentBranch?: (cwd: string) => Promise<string | null>;
now?: () => number;
watchPollMs?: number;
watchInitialDelayMs?: number;
}
/**
@@ -180,14 +195,6 @@ const GiteaIssueListItemSchema = z
})
.passthrough();
const GiteaLoginSchema = z
.object({
name: z.string().optional(),
url: z.string().optional(),
ssh_host: z.string().optional(),
})
.passthrough();
const GiteaUserSchema = z
.object({
login: z.string().optional(),
@@ -288,55 +295,6 @@ const GiteaCurrentPullRequestApiSchema = z
})
.passthrough();
const GiteaCommitStatusSchema = z
.object({
id: z.number(),
status: z.string(),
target_url: z.string().nullable().optional(),
description: z.string().nullable().optional(),
url: z.string().nullable().optional(),
context: z.string().optional().default(""),
creator: z.unknown().nullable().optional(),
})
.passthrough();
const GiteaCombinedCommitStatusSchema = z
.object({
state: z.string().optional().default(""),
sha: z.string().optional(),
total_count: z.number().optional(),
statuses: z.array(GiteaCommitStatusSchema).optional().default([]),
})
.passthrough();
const GiteaActionTaskSchema = z
.object({
id: z.number(),
name: z.string().nullable().optional(),
head_branch: z.string().nullable().optional(),
head_sha: z.string(),
run_number: z.number().optional(),
event: z.string().nullable().optional(),
display_title: z.string().nullable().optional(),
status: z.string(),
need_approval: z.boolean().optional().default(false),
workflow_id: z.string().nullable().optional(),
url: z.string().nullable().optional(),
created_at: z.string().nullable().optional(),
run_started_at: z.string().nullable().optional(),
})
.passthrough();
// The item shape is validated per-task rather than as `z.array(GiteaActionTaskSchema)`
// so one malformed task (missing id/status/head_sha) drops only itself instead of
// throwing out the whole page and zeroing every Actions check for the PR.
const GiteaActionsListResponseSchema = z
.object({
workflow_runs: z.array(z.unknown()).optional().default([]),
total_count: z.number().optional(),
})
.passthrough();
const GiteaActionRunPullRequestRefSchema = z
.object({
repo: z.object({ id: z.number().optional() }).passthrough().nullable().optional(),
@@ -410,9 +368,6 @@ type GiteaPrListItem = z.infer<typeof GiteaPrListItemSchema>;
type GiteaIssueListItem = z.infer<typeof GiteaIssueListItemSchema>;
type GiteaPullRequestView = z.infer<typeof GiteaPullRequestViewSchema>;
type GiteaCurrentPullRequestApi = z.infer<typeof GiteaCurrentPullRequestApiSchema>;
type GiteaCommitStatus = z.infer<typeof GiteaCommitStatusSchema>;
type GiteaCombinedCommitStatus = z.infer<typeof GiteaCombinedCommitStatusSchema>;
type GiteaActionTask = z.infer<typeof GiteaActionTaskSchema>;
type GiteaIssueComment = z.infer<typeof GiteaIssueCommentSchema>;
type GiteaReview = z.infer<typeof GiteaReviewSchema>;
type GiteaReviewComment = z.infer<typeof GiteaReviewCommentSchema>;
@@ -797,10 +752,6 @@ function deriveGiteaActionRequiredRunIds(runs: unknown[], sha: string): Set<numb
return runIds;
}
function getGiteaActionTaskName(task: GiteaActionTask): string {
return task.name || task.display_title || task.workflow_id || `actions-${task.id}`;
}
function toGiteaActionTaskCheck(task: GiteaActionTask): PullRequestCheck {
const rawStatus = task.status.toLowerCase();
return {
@@ -814,136 +765,6 @@ function toGiteaActionTaskCheck(task: GiteaActionTask): PullRequestCheck {
};
}
function getGiteaActionWorkflowIdentity(task: GiteaActionTask): string {
if (task.workflow_id) {
return `workflow\u0000${task.workflow_id}`;
}
// Instances that omit workflow_id (older Gitea/Forgejo payloads) still need
// reruns of the same job collapsed to the latest execution, so fall back to
// the job name before treating the task as its own group.
const name = task.name || task.display_title;
if (name) {
return `name\u0000${name}`;
}
return `task\u0000${getGiteaActionExecutionIdentity(task)}`;
}
function getGiteaActionExecutionIdentity(task: GiteaActionTask): string {
if (task.run_number !== undefined) return `run-number\u0000${task.run_number}`;
const runId = getGiteaActionRunIdFromUrl(task.url);
if (runId !== null) return `run-id\u0000${runId}`;
if (task.url) return `url\u0000${task.url}`;
return `task\u0000${task.id}`;
}
function parseGiteaActionTaskTime(task: GiteaActionTask): number {
const timestamp = task.created_at ?? task.run_started_at ?? null;
if (!timestamp) {
return 0;
}
const time = Date.parse(timestamp);
return Number.isNaN(time) ? 0 : time;
}
function compareGiteaActionTaskRecency(left: GiteaActionTask, right: GiteaActionTask): number {
const leftRunNumber = left.run_number ?? 0;
const rightRunNumber = right.run_number ?? 0;
if (leftRunNumber !== rightRunNumber) {
return leftRunNumber - rightRunNumber;
}
const leftTime = parseGiteaActionTaskTime(left);
const rightTime = parseGiteaActionTaskTime(right);
if (leftTime !== rightTime) {
return leftTime - rightTime;
}
return left.id - right.id;
}
function parseGiteaActionTasks(rawTasks: unknown[]): GiteaActionTask[] {
const tasks: GiteaActionTask[] = [];
for (const raw of rawTasks) {
const parsed = GiteaActionTaskSchema.safeParse(raw);
if (parsed.success) {
tasks.push(parsed.data);
}
}
return tasks;
}
function latestGiteaActionTasksByWorkflow(tasks: GiteaActionTask[]): GiteaActionTask[] {
const latestExecutions = new Map<string, GiteaActionTask>();
for (const task of tasks) {
const identity = getGiteaActionWorkflowIdentity(task);
const current = latestExecutions.get(identity);
if (!current || compareGiteaActionTaskRecency(current, task) < 0) {
latestExecutions.set(identity, task);
}
}
return tasks.filter((task) => {
const latest = latestExecutions.get(getGiteaActionWorkflowIdentity(task));
return (
latest !== undefined &&
getGiteaActionExecutionIdentity(task) === getGiteaActionExecutionIdentity(latest)
);
});
}
function getUrlOrigin(value: string | null | undefined): string | null {
if (!value) return null;
try {
return new URL(value).origin;
} catch {
return null;
}
}
const GITEA_RELATIVE_URL_ORIGIN = "https://gitea.invalid";
function getGiteaActionRunIdFromUrl(value: string | null | undefined): number | null {
if (!value) return null;
try {
const url = new URL(value, GITEA_RELATIVE_URL_ORIGIN);
const match = url.pathname.match(/\/actions\/runs\/(\d+)(?:\/jobs\/\d+)?\/?$/);
return match?.[1] ? Number.parseInt(match[1], 10) : null;
} catch {
return null;
}
}
function isNativeActionJobUrl(
targetUrl: string | null | undefined,
nativeOrigins: ReadonlySet<string>,
nativeRunIds: ReadonlySet<number>,
): boolean {
if (!targetUrl) return false;
try {
const url = new URL(targetUrl, GITEA_RELATIVE_URL_ORIGIN);
if (!/\/actions\/runs\/\d+\/jobs\/\d+\/?$/.test(url.pathname)) return false;
if (url.origin !== GITEA_RELATIVE_URL_ORIGIN && !nativeOrigins.has(url.origin)) return false;
const runId = getGiteaActionRunIdFromUrl(targetUrl);
return runId !== null && nativeRunIds.has(runId);
} catch {
return false;
}
}
// A "shadow" is the commit status Gitea synthesizes to mirror one of its own
// Actions jobs; keeping both would double-report every job. Detection is purely
// structural: Gitea always creates these statuses with a target_url of the form
// "<run link>/jobs/<job id>" (services/actions/commit_status.go upstream), so a
// status is a shadow exactly when its URL points at a job of a run we actually
// fetched from the Actions API. Anything else - external CI, URL-less statuses,
// contexts that merely look like "<workflow> / <job> (<event>)" - is kept.
function isGiteaActionShadowStatus(
status: GiteaCommitStatus,
nativeOrigins: ReadonlySet<string>,
nativeRunIds: ReadonlySet<number>,
): boolean {
return isNativeActionJobUrl(status.target_url, nativeOrigins, nativeRunIds);
}
function combineGiteaChecks(
commitStatuses: GiteaCommitStatus[],
actionTasks: GiteaActionTask[],
@@ -1219,32 +1040,6 @@ export async function probeGiteaHost(host: string): Promise<boolean> {
}
}
function findTeaLoginNameForHost(stdout: string, host: string): string | null {
let data: unknown;
try {
data = JSON.parse(stdout);
} catch {
return null;
}
const parsed = z.array(GiteaLoginSchema).safeParse(data);
if (!parsed.success) {
return null;
}
const target = host.toLowerCase();
const match = parsed.data.find((login) => {
const candidates = [login.ssh_host, login.name];
if (login.url) {
try {
candidates.push(new URL(login.url).hostname);
} catch {
// ignore malformed login url
}
}
return candidates.some((candidate) => candidate?.toLowerCase() === target);
});
return match?.name ?? null;
}
function hostHasLogin(stdout: string, host: string): boolean {
return findTeaLoginNameForHost(stdout, host) !== null;
}
@@ -1409,19 +1204,35 @@ export function createGiteaService(options: CreateGiteaServiceOptions = {}): For
const now = options.now ?? Date.now;
const currentPrHeadShaCache = new Map<string, { sha: string; expiresAt: number }>();
async function run(args: string[], runOptions: TeaCommandRunnerOptions): Promise<string> {
async function runRaw(
args: string[],
runOptions: TeaCommandRunnerOptions,
): Promise<TeaCommandResult> {
const teaPath = await resolveTea();
if (!teaPath) {
throw new TeaCliMissingError();
}
try {
const result = await runner(args, runOptions);
return result.stdout.trim();
return await runner(args, runOptions);
} catch (error) {
throw teaCliRunner.normalizeError(error, { args: redactTeaArgs(args), cwd: runOptions.cwd });
}
}
async function run(args: string[], runOptions: TeaCommandRunnerOptions): Promise<string> {
const result = await runRaw(args, runOptions);
return result.stdout.trim();
}
const changeRequests = createGiteaChangeRequestSource({
runCommand: runRaw,
createAuthError: (stderr) => new TeaAuthenticationError({ stderr }),
createCommandError: (params) => new TeaCommandError(params),
now,
pollIntervalMs: options.watchPollMs,
initialDelayMs: options.watchInitialDelayMs,
});
function runJsonParse<T>(
args: string[],
runOptions: TeaCommandRunnerOptions,
@@ -2359,6 +2170,8 @@ export function createGiteaService(options: CreateGiteaServiceOptions = {}): For
return notSupported("disablePullRequestAutoMerge");
},
changeRequests,
invalidate(input: { cwd: string }): void {
const prefix = `${input.cwd}:`;
for (const key of currentPrHeadShaCache.keys()) {
@@ -2367,5 +2180,9 @@ export function createGiteaService(options: CreateGiteaServiceOptions = {}): For
}
}
},
dispose(): void {
changeRequests.dispose();
},
};
}
File diff suppressed because it is too large Load Diff
@@ -0,0 +1,917 @@
import { z } from "zod";
import { normalizeHost } from "@getpaseo/protocol/git-remote";
import { GITLAB_ACTIVE_PIPELINE_STATUS_SET } from "@getpaseo/protocol/gitlab-pipeline";
import {
ChangeRequestRateLimitError,
createPerHostChangeRequestPoller,
parseCliHttpResponse,
parseRetryAfterMs,
type PerHostReadContext,
} from "./change-request-poller.js";
import type { ChangeRequestSnapshot, ChangeRequestSource } from "./change-request-source.js";
const GITLAB_CLOUD_HOST = "gitlab.com";
const GITLAB_PAGE_SIZE = 100;
const GITLAB_MR_TABS = new Set(["diffs", "commits", "pipelines", "builds", "reports"]);
const checkUrlSchema = z.url({ protocol: /^https?$/ });
const gitLabWatchPipelineSchema = z
.object({
id: z.number(),
project_id: z.number().nullable().optional(),
sha: z.string().nullable().optional(),
status: z.string(),
web_url: z.string().nullable().optional(),
})
.passthrough();
const gitLabWatchMrSchema = z
.object({
iid: z.number(),
state: z.string(),
sha: z.string().nullable().optional(),
diff_refs: z
.object({
head_sha: z.string().nullable().optional(),
})
.passthrough()
.nullable()
.optional(),
web_url: checkUrlSchema,
target_project_id: z.number().nullable().optional(),
merged_at: z.string().nullable().optional(),
head_pipeline: gitLabWatchPipelineSchema.nullable().optional(),
})
.passthrough();
const gitLabWatchJobSchema = z
.object({
id: z.number(),
name: z.string(),
status: z.string(),
allow_failure: z.boolean().optional(),
web_url: z.string().nullable().optional(),
})
.passthrough();
const gitLabWatchNoteAuthorSchema = z
.object({
username: z.string().optional(),
name: z.string().optional(),
})
.passthrough();
const gitLabWatchNoteSchema = z
.object({
id: z.number(),
body: z.string().nullable().optional(),
system: z.boolean().optional(),
type: z.string().nullable().optional(),
position: z.unknown().nullable().optional(),
author: gitLabWatchNoteAuthorSchema.nullable().optional(),
})
.passthrough();
const gitLabWatchDiscussionSchema = z
.object({
id: z.string(),
notes: z.array(gitLabWatchNoteSchema).optional().default([]),
})
.passthrough();
const gitLabWatchApprovalsSchema = z
.object({
approvals_required: z.number().nullable().optional(),
approvals_left: z.number().nullable().optional(),
})
.passthrough();
type GitLabWatchMr = z.infer<typeof gitLabWatchMrSchema>;
type GitLabWatchJob = z.infer<typeof gitLabWatchJobSchema>;
type GitLabWatchNote = z.infer<typeof gitLabWatchNoteSchema>;
type GitLabWatchDiscussion = z.infer<typeof gitLabWatchDiscussionSchema>;
type GitLabWatchApprovals = z.infer<typeof gitLabWatchApprovalsSchema>;
interface GitLabMergeRequestIdentity {
protocol: "http:" | "https:";
host: string;
port: string;
hostWithPort: string;
projectPath: string;
iid: number;
}
function invalidGitLabUrl(): never {
throw new Error("Enter a GitLab merge request URL.");
}
function parseGitLabUrlOrigin(input: string): {
protocol: "http:" | "https:";
host: string;
port: string;
hostWithPort: string;
pathname: string;
} {
const trimmed = input.trim();
if (!trimmed || /\s/.test(trimmed)) invalidGitLabUrl();
let parsed: URL;
try {
parsed = new URL(trimmed);
} catch {
invalidGitLabUrl();
}
const protocol = parsed.protocol.toLowerCase();
if ((protocol !== "https:" && protocol !== "http:") || parsed.username || parsed.password) {
invalidGitLabUrl();
}
const host = normalizeHost(parsed.hostname);
if (!host || (host === GITLAB_CLOUD_HOST && protocol !== "https:")) {
invalidGitLabUrl();
}
return {
protocol: protocol as "http:" | "https:",
host,
port: parsed.port,
hostWithPort: parsed.port ? `${host}:${parsed.port}` : host,
pathname: parsed.pathname,
};
}
function decodeGitLabProjectPath(rawSegments: string[]): string {
if (rawSegments.length < 2) invalidGitLabUrl();
const decodedSegments: string[] = [];
for (const segment of rawSegments) {
let decoded: string;
try {
decoded = decodeURIComponent(segment);
} catch {
invalidGitLabUrl();
}
const invalidSegment =
!decoded ||
decoded === "." ||
decoded === ".." ||
decoded === "-" ||
decoded.includes("/") ||
decoded.includes("\\");
if (invalidSegment) invalidGitLabUrl();
decodedSegments.push(decoded);
}
return decodedSegments.join("/");
}
function parseGitLabMergeRequestUrl(input: string): GitLabMergeRequestIdentity {
const origin = parseGitLabUrlOrigin(input);
const rawSegments = origin.pathname.split("/").filter((segment) => segment.length > 0);
if (rawSegments.length < 4) invalidGitLabUrl();
// Strip an optional browser tab suffix (e.g. /diffs, /commits, /pipelines).
if (
rawSegments.length >= 5 &&
GITLAB_MR_TABS.has(rawSegments[rawSegments.length - 1]!.toLowerCase()) &&
/^\d+$/.test(rawSegments[rawSegments.length - 2]!)
) {
rawSegments.pop();
}
const iidRaw = rawSegments.pop();
const resource = rawSegments.pop();
if (!iidRaw || !/^\d+$/.test(iidRaw) || resource?.toLowerCase() !== "merge_requests") {
invalidGitLabUrl();
}
const iid = Number(iidRaw);
if (!Number.isInteger(iid) || iid < 1 || iid > 2_147_483_647) {
invalidGitLabUrl();
}
// Modern GitLab URLs place `-` before `merge_requests`; legacy URLs omit it.
if (rawSegments[rawSegments.length - 1] === "-") {
rawSegments.pop();
}
return {
protocol: origin.protocol,
host: origin.host,
port: origin.port,
hostWithPort: origin.hostWithPort,
projectPath: decodeGitLabProjectPath(rawSegments),
iid,
};
}
export function resolveGitLabChangeRequest(input: string): string {
const { protocol, hostWithPort, projectPath, iid } = parseGitLabMergeRequestUrl(input);
return `${protocol}//${hostWithPort}/${projectPath}/-/merge_requests/${iid}`;
}
export function gitlabChangeRequestHost(url: string): string {
return parseGitLabMergeRequestUrl(url).hostWithPort;
}
export function describeGitLabChangeRequest(url: string): string {
const { host, port, hostWithPort, projectPath, iid } = parseGitLabMergeRequestUrl(url);
const project =
host === GITLAB_CLOUD_HOST && !port ? projectPath : `${hostWithPort}/${projectPath}`;
return `${project} !${iid}`;
}
function mapGitLabMrState(mr: GitLabWatchMr): ChangeRequestSnapshot["state"] {
const state = mr.state.toLowerCase();
// GitLab reports "locked" while a merge is actively in progress; treat it as
// open so polling continues until GitLab transitions to "merged" (or "closed").
if (state === "opened" || state === "locked") return "open";
if (state === "merged" || mr.merged_at != null) return "merged";
return "closed";
}
function mapGitLabPipelineState(
status: string | null | undefined,
): ChangeRequestSnapshot["checksState"] {
if (!status) return "neutral";
const normalized = status.toLowerCase();
if (normalized === "success" || normalized === "passed") return "passed";
if (normalized === "failed") return "failed";
if (normalized === "manual" || GITLAB_ACTIVE_PIPELINE_STATUS_SET.has(normalized)) {
return "pending";
}
return "neutral";
}
function mapGitLabJobState(job: GitLabWatchJob): ChangeRequestSnapshot["checks"][number]["state"] {
const raw = job.status.toLowerCase();
const allowFailure = job.allow_failure ?? false;
if (raw === "failed") return allowFailure ? "neutral" : "failed";
if (raw === "success" || raw === "passed") return "passed";
if (raw === "manual") return allowFailure ? "neutral" : "pending";
if (GITLAB_ACTIVE_PIPELINE_STATUS_SET.has(raw)) return "pending";
return "neutral";
}
function toWatchCheck(
job: GitLabWatchJob,
prefix: "job" | "bridge",
): ChangeRequestSnapshot["checks"][number] {
const url = checkUrlSchema.safeParse(job.web_url).data;
return {
id: `${prefix}:${job.id}`,
name: job.name,
state: mapGitLabJobState(job),
...(url ? { url } : {}),
};
}
type ApprovalNoteAction = "approved" | "unapproved" | "reset";
interface ParsedApprovalNote {
id: string;
action: ApprovalNoteAction;
actor: string | null;
url: string;
}
function parseGitLabApprovalNote(
note: GitLabWatchNote,
mrWebUrl: string,
): ParsedApprovalNote | null {
if (note.system !== true) return null;
const body = note.body?.trim().toLowerCase() ?? "";
if (!body) return null;
let action: ApprovalNoteAction | null = null;
if (body === "approved this merge request" || body.startsWith("approved this merge request")) {
action = "approved";
} else if (
body === "unapproved this merge request" ||
body.startsWith("unapproved this merge request") ||
body.startsWith("removed approval") ||
body.startsWith("revoked approval")
) {
action = "unapproved";
} else if (body.startsWith("reset approvals")) {
action = "reset";
}
if (!action) return null;
const actor = note.author?.username?.trim() || note.author?.name?.trim() || null;
return {
id: `approval-note:${note.id}`,
action,
actor,
url: `${mrWebUrl}#note_${note.id}`,
};
}
interface ApprovalCount {
given: number;
required: number;
}
function summarizeApprovalCount(approvals: GitLabWatchApprovals): ApprovalCount | null {
const { approvals_required: required, approvals_left: remaining } = approvals;
if (required == null || remaining == null) return null;
return { given: Math.max(0, required - remaining), required };
}
function formatApprovalCount(summary: ApprovalCount | null): string {
if (!summary || summary.required <= 0) return "";
return ` (${summary.given}/${summary.required} approvals)`;
}
function formatApprovalActor(actor: string | null): string {
if (!actor) return "";
return actor.startsWith("@") ? actor : `@${actor}`;
}
function formatApprovalNoteMessage(
note: ParsedApprovalNote,
summary: ApprovalCount | null,
): string {
const actor = formatApprovalActor(note.actor);
const count = formatApprovalCount(summary);
if (note.action === "approved") {
return `Merge request approved${actor ? ` by ${actor}` : ""}${count}: ${note.url}`;
}
if (note.action === "unapproved") {
return `Merge request approval removed${actor ? ` by ${actor}` : ""}${count}: ${note.url}`;
}
return `Merge request approvals reset${actor ? ` by ${actor}` : ""}${count}: ${note.url}`;
}
interface ParsedDiscussionItems {
humanActivity: ChangeRequestSnapshot["activity"];
approvalNotes: ParsedApprovalNote[];
}
function parseDiscussionItems(
discussions: GitLabWatchDiscussion[],
mrWebUrl: string,
): ParsedDiscussionItems {
const humanActivity: ChangeRequestSnapshot["activity"] = [];
const approvalNotes: ParsedApprovalNote[] = [];
for (const discussion of discussions) {
for (const note of discussion.notes) {
if (note.system === true) {
const approvalNote = parseGitLabApprovalNote(note, mrWebUrl);
if (approvalNote) approvalNotes.push(approvalNote);
continue;
}
const isInline = note.position != null || note.type === "DiffNote";
humanActivity.push({
id: isInline ? `inline:${note.id}` : `comment:${note.id}`,
kind: isInline ? "inline comment" : "comment",
url: `${mrWebUrl}#note_${note.id}`,
});
}
}
return { humanActivity, approvalNotes };
}
function resolvePipelineProjectId(
pipeline: z.infer<typeof gitLabWatchPipelineSchema>,
mr: GitLabWatchMr,
encodedProject: string,
): string {
if (pipeline.project_id != null) return String(pipeline.project_id);
if (mr.target_project_id != null) return String(mr.target_project_id);
return encodedProject;
}
function pipelineFailureCheck(
pipeline: z.infer<typeof gitLabWatchPipelineSchema>,
): ChangeRequestSnapshot["checks"][number] {
const url = checkUrlSchema.safeParse(pipeline.web_url).data;
return {
id: `pipeline:${pipeline.id}`,
name: `Pipeline #${pipeline.id}`,
state: "failed",
...(url ? { url } : {}),
};
}
function createRateLimitError(
host: string,
nowMs: number,
headers: ReadonlyMap<string, string>,
): ChangeRequestRateLimitError {
const resetAtMs = parseRetryAfterMs(headers, nowMs, {
forceOnMissing: true,
defaultPauseMs: 60_000,
})!;
return new ChangeRequestRateLimitError({ host, resetAtMs });
}
function extractRateLimitFromFailedCommand(
host: string,
nowMs: number,
status: number | null,
headers: ReadonlyMap<string, string>,
text: string,
): ChangeRequestRateLimitError | null {
if (status !== null) {
return status === 429 ? createRateLimitError(host, nowMs, headers) : null;
}
if (!/\b(429|too many requests|rate limit)\b/i.test(text)) return null;
return createRateLimitError(host, nowMs, headers);
}
export interface CreateGitLabChangeRequestSourceOptions {
runCommand(
args: string[],
options: { cwd: string; envOverlay?: Record<string, string> },
): Promise<{ stdout: string; stderr: string }>;
isAuthError(error: unknown): boolean;
isCommandError(error: unknown): error is Error & { stderr: string; stdout?: string };
createAuthError(stderr: string): Error;
createCommandError(params: {
args: string[];
cwd: string;
exitCode: number | null;
stderr: string;
stdout?: string;
}): Error;
now?: () => number;
pollIntervalMs?: number;
initialDelayMs?: number;
}
export function createGitLabChangeRequestSource(
options: CreateGitLabChangeRequestSourceOptions,
): ChangeRequestSource & { dispose(): void } {
const now = options.now ?? Date.now;
async function readConfig(
host: string,
key: string,
envOverlay: Record<string, string> = {},
): Promise<string> {
const config = await options.runCommand(["config", "get", key, "--host", host], {
cwd: process.cwd(),
envOverlay: { GITLAB_HOST: host, ...envOverlay },
});
return config.stdout.trim();
}
async function preferredProfileHost(identity: GitLabMergeRequestIdentity): Promise<string> {
const { host, hostWithPort } = identity;
if (hostWithPort === host) return host;
// An API host override applies to either profile. Use the configured value
// to decide which profile to try first, then check access through the MR.
const exactProfile = await readConfig(hostWithPort, "api_host", { GITLAB_API_HOST: "" });
return exactProfile ? hostWithPort : host;
}
async function readApiPrefix(profileHost: string): Promise<string> {
if (profileHost === GITLAB_CLOUD_HOST) return "";
const trimSlashes = /^\/+|\/+$/g;
let prefix = (await readConfig(profileHost, "subfolder")).replace(trimSlashes, "");
if (!prefix) {
const apiHost = await readConfig(profileHost, "api_host");
if (apiHost) {
const apiUrl = new URL(apiHost.includes("://") ? apiHost : `https://${apiHost}`);
prefix = apiUrl.pathname.replace(trimSlashes, "");
}
}
return decodeURI(prefix);
}
function parseJsonResponseBody<T>(params: {
args: string[];
cwd: string;
body: string;
schema: z.ZodType<T>;
}): T {
let json: unknown;
try {
json = JSON.parse(params.body);
} catch {
throw options.createCommandError({
args: params.args,
cwd: params.cwd,
exitCode: null,
stderr: `glab did not return valid JSON (${params.body.length} bytes)`,
});
}
const validated = params.schema.safeParse(json);
if (!validated.success) {
throw options.createCommandError({
args: params.args,
cwd: params.cwd,
exitCode: null,
stderr: `glab JSON did not match the expected schema: ${validated.error.message}`,
});
}
return validated.data;
}
function checkHttpStatus(params: {
host: string;
args: string[];
cwd: string;
status: number | null;
headers: ReadonlyMap<string, string>;
body: string;
rawStdout: string;
rawStderr: string;
pauseHost(untilMs: number): void;
}): void {
// Only decide rate limits from the HTTP status code on parsed responses so
// ordinary MR titles, comments, or IIDs mentioning "429" or "rate limit"
// never trip a false rate-limit pause.
if (params.status === null) return;
if (params.status === 429) {
const error = createRateLimitError(params.host, now(), params.headers);
params.pauseHost(error.resetAtMs);
throw error;
}
if (params.status === 401) {
throw options.createAuthError(params.body || params.rawStderr || "401 Unauthorized");
}
if (params.status < 200 || params.status >= 300) {
throw options.createCommandError({
args: params.args,
cwd: params.cwd,
exitCode: null,
stderr: `HTTP ${params.status}: ${params.body || params.rawStderr}`.trim(),
stdout: params.rawStdout,
});
}
}
async function apiGet<T>(params: {
host: string;
endpoint: string;
schema: z.ZodType<T>;
poll: PerHostReadContext;
}): Promise<{ data: T; headers: ReadonlyMap<string, string> }> {
if (!params.poll.isObserved()) throw new Error("Change request observation ended");
params.poll.assertHostAvailable();
// glab api rejects a port in --hostname. GITLAB_HOST selects that profile.
const args = params.host.includes(":")
? ["api", "-i", params.endpoint]
: ["api", "--hostname", params.host, "-i", params.endpoint];
const cwd = process.cwd();
let result: { stdout: string; stderr: string };
try {
result = await options.runCommand(args, {
cwd,
envOverlay: { GITLAB_HOST: params.host },
});
} catch (error) {
if (options.isCommandError(error)) {
const parsedError = error.stdout ? parseCliHttpResponse(error.stdout) : null;
const rateLimit = extractRateLimitFromFailedCommand(
params.host,
now(),
parsedError?.status ?? null,
parsedError?.headers ?? new Map(),
`${error.stderr}\n${error.stdout ?? ""}`,
);
if (rateLimit) {
params.poll.pauseHost(rateLimit.resetAtMs);
throw rateLimit;
}
}
throw error;
}
const parsed = parseCliHttpResponse(result.stdout);
checkHttpStatus({
host: params.host,
args,
cwd,
status: parsed.status,
headers: parsed.headers,
body: parsed.body,
rawStdout: result.stdout,
rawStderr: result.stderr,
pauseHost: params.poll.pauseHost,
});
const proactivePause = parseRetryAfterMs(parsed.headers, now());
if (proactivePause !== null) {
params.poll.deferPollsUntil(proactivePause);
}
const data = parseJsonResponseBody({ args, cwd, body: parsed.body, schema: params.schema });
return { data, headers: parsed.headers };
}
async function apiGetAllPages<T>(params: {
host: string;
endpoint: string;
itemSchema: z.ZodType<T>;
poll: PerHostReadContext;
}): Promise<{ items: T[]; pagesRead: number }> {
const items: T[] = [];
const schema = z.array(params.itemSchema);
const seenPages = new Set<number>([1]);
let page = 1;
let pagesRead = 0;
while (true) {
if (!params.poll.isObserved()) {
return { items, pagesRead };
}
const sep = params.endpoint.includes("?") ? "&" : "?";
const response = await apiGet({
host: params.host,
endpoint: `${params.endpoint}${sep}per_page=${GITLAB_PAGE_SIZE}&page=${page}`,
schema,
poll: params.poll,
});
pagesRead += 1;
items.push(...response.data);
const nextPageHeader = response.headers.get("x-next-page");
if (nextPageHeader !== undefined) {
const trimmed = nextPageHeader.trim();
if (!trimmed) break;
const nextPage = Number(trimmed);
if (!Number.isInteger(nextPage) || nextPage <= 0 || seenPages.has(nextPage)) {
throw new Error("GitLab returned an invalid pagination header.");
}
seenPages.add(nextPage);
page = nextPage;
} else {
if (response.data.length < GITLAB_PAGE_SIZE) break;
page += 1;
seenPages.add(page);
}
}
return { items, pagesRead };
}
function commandErrorStatus(error: unknown): number | null {
return options.isCommandError(error) && error.stdout
? parseCliHttpResponse(error.stdout).status
: null;
}
async function readMergeRequestMetadata(params: {
host: string;
identity: GitLabMergeRequestIdentity;
endpoint: string;
poll: PerHostReadContext;
}): Promise<GitLabWatchMr> {
const { data: mr } = await apiGet({
host: params.host,
endpoint: params.endpoint,
schema: gitLabWatchMrSchema,
poll: params.poll,
});
const address = parseGitLabMergeRequestUrl(mr.web_url);
const expected = params.identity;
if (address.protocol !== expected.protocol || address.hostWithPort !== expected.hostWithPort) {
throw new Error(
`GitLab returned a merge request from a different web origin: ${address.protocol}//${address.hostWithPort}`,
);
}
if (address.projectPath.toLowerCase() !== expected.projectPath.toLowerCase()) {
throw new Error("GitLab returned a merge request from a different project.");
}
if (address.iid !== expected.iid || mr.iid !== expected.iid) {
throw new Error("GitLab returned a different merge request number.");
}
return mr;
}
function pipelineDetailsUnavailable(error: unknown): boolean {
const status = commandErrorStatus(error);
return status === 403 || status === 404;
}
async function readPipelineChecks(params: {
host: string;
identity: GitLabMergeRequestIdentity;
mrEndpoint: string;
encodedProject: string;
mr: GitLabWatchMr;
headSha: string;
poll: PerHostReadContext;
}): Promise<ChangeRequestSnapshot["checks"]> {
const pipeline = params.mr.head_pipeline;
if (!pipeline) return [];
const pipelineProject = resolvePipelineProjectId(pipeline, params.mr, params.encodedProject);
let jobsResult: { items: GitLabWatchJob[]; pagesRead: number };
try {
jobsResult = await apiGetAllPages({
host: params.host,
endpoint: `projects/${pipelineProject}/pipelines/${pipeline.id}/jobs`,
itemSchema: gitLabWatchJobSchema,
poll: params.poll,
});
} catch (error) {
if (!pipelineDetailsUnavailable(error)) throw error;
// The MR can expose pipeline status even when its jobs are restricted.
return mapGitLabPipelineState(pipeline.status) === "failed"
? [pipelineFailureCheck(pipeline)]
: [];
}
if (!params.poll.isObserved()) {
throw new Error("Change request observation ended");
}
const checks = jobsResult.items.map((job) => toWatchCheck(job, "job"));
let fetchedBridges = false;
if (
mapGitLabPipelineState(pipeline.status) === "failed" &&
!checks.some((check) => check.state === "failed")
) {
fetchedBridges = true;
await appendFailedBridgeOrPipelineChecks({
host: params.host,
pipelineProject,
pipeline,
checks,
poll: params.poll,
});
}
// Guard against headSha or head_pipeline shifting while paginating check pages.
if (jobsResult.pagesRead > 1 || fetchedBridges) {
const recheck = await readMergeRequestMetadata({
host: params.host,
identity: params.identity,
endpoint: params.mrEndpoint,
poll: params.poll,
});
const recheckSha = recheck.sha || recheck.diff_refs?.head_sha || "";
if (
recheckSha !== params.headSha ||
recheck.head_pipeline?.id !== pipeline.id ||
recheck.head_pipeline?.status !== pipeline.status
) {
throw new Error("The merge request head or pipeline changed during pagination.");
}
}
return checks;
}
async function appendFailedBridgeOrPipelineChecks(params: {
host: string;
pipelineProject: string;
pipeline: z.infer<typeof gitLabWatchPipelineSchema>;
checks: ChangeRequestSnapshot["checks"];
poll: PerHostReadContext;
}): Promise<void> {
try {
const bridgesResult = await apiGetAllPages({
host: params.host,
endpoint: `projects/${params.pipelineProject}/pipelines/${params.pipeline.id}/bridges`,
itemSchema: gitLabWatchJobSchema,
poll: params.poll,
});
for (const bridge of bridgesResult.items) {
params.checks.push(toWatchCheck(bridge, "bridge"));
}
} catch (error) {
if (!pipelineDetailsUnavailable(error)) throw error;
}
if (!params.checks.some((check) => check.state === "failed")) {
params.checks.push(pipelineFailureCheck(params.pipeline));
}
}
async function readOptionalApprovalCount(params: {
host: string;
endpoint: string;
poll: PerHostReadContext;
}): Promise<ApprovalCount | null> {
try {
const { data: approvals } = await apiGet({
host: params.host,
endpoint: params.endpoint,
schema: gitLabWatchApprovalsSchema,
poll: params.poll,
});
return summarizeApprovalCount(approvals);
} catch {
// The approval system note is complete without an API count.
return null;
}
}
async function readInitialMergeRequest(
identity: GitLabMergeRequestIdentity,
poll: PerHostReadContext,
) {
async function readUsing(host: string) {
const { projectPath, iid } = identity;
const prefix = await readApiPrefix(host);
const relativePath =
prefix && projectPath.startsWith(`${prefix}/`)
? projectPath.slice(prefix.length + 1)
: projectPath;
const encodedProject = encodeURIComponent(
relativePath.includes("/") ? relativePath : projectPath,
);
const mrEndpoint = `projects/${encodedProject}/merge_requests/${iid}`;
const mr = await readMergeRequestMetadata({ host, identity, endpoint: mrEndpoint, poll });
return { host, encodedProject, mrEndpoint, mr };
}
const preferred = await preferredProfileHost(identity);
try {
return await readUsing(preferred);
} catch (error) {
const status = commandErrorStatus(error);
const accessDenied = options.isAuthError(error) || status === 403 || status === 404;
if (preferred === identity.host || !accessDenied) throw error;
return readUsing(identity.host);
}
}
async function readMergeRequest(context: PerHostReadContext): Promise<ChangeRequestSnapshot> {
const identity = parseGitLabMergeRequestUrl(context.url);
const { iid } = identity;
const { host, encodedProject, mrEndpoint, mr } = await readInitialMergeRequest(
identity,
context,
);
const headSha = mr.sha || mr.diff_refs?.head_sha || "";
if (!headSha) {
throw new Error(`GitLab merge request !${iid} did not include a head commit SHA.`);
}
const checks = await readPipelineChecks({
host,
identity,
mrEndpoint,
encodedProject,
mr,
headSha,
poll: context,
});
const discussionsResult = await apiGetAllPages({
host,
endpoint: `projects/${encodedProject}/merge_requests/${iid}/discussions`,
itemSchema: gitLabWatchDiscussionSchema,
poll: context,
});
if (!context.isObserved()) {
throw new Error("Change request observation ended");
}
const { humanActivity, approvalNotes } = parseDiscussionItems(
discussionsResult.items,
mr.web_url,
);
const known = context.knownActivity();
const hasNewApprovalNote =
known !== undefined && approvalNotes.some((note) => !known.has(note.id));
// Fetch /approvals only to enrich a newly observed approval system note with
// current counts — keeping seenActivity as the single persisted owner of
// approval transition baselines.
const approvalCount = hasNewApprovalNote
? await readOptionalApprovalCount({
host,
endpoint: `projects/${encodedProject}/merge_requests/${iid}/approvals`,
poll: context,
})
: null;
const activity: ChangeRequestSnapshot["activity"] = [
...humanActivity,
...approvalNotes.map((note) => ({
id: note.id,
kind: "approval" as const,
url: note.url,
message: formatApprovalNoteMessage(note, approvalCount),
})),
];
return {
state: mapGitLabMrState(mr),
headSha,
checksState: mapGitLabPipelineState(mr.head_pipeline?.status),
checks,
reviewDecision: null,
activity,
};
}
const poller = createPerHostChangeRequestPoller({
hostOf: gitlabChangeRequestHost,
read: readMergeRequest,
now,
pollIntervalMs: options.pollIntervalMs,
initialDelayMs: options.initialDelayMs,
});
return {
resolve: resolveGitLabChangeRequest,
describe: describeGitLabChangeRequest,
observe(url, callbacks) {
return poller.observe(url, callbacks);
},
dispose() {
poller.dispose();
},
};
}
+31 -3
View File
@@ -60,6 +60,7 @@ import {
CHECK_TRAIT_WARNING,
} from "@getpaseo/protocol/check-traits";
import { GITLAB_ACTIVE_PIPELINE_STATUS_SET } from "@getpaseo/protocol/gitlab-pipeline";
import { createGitLabChangeRequestSource } from "./gitlab-change-requests.js";
import { isGitLabStatusFacts, type GitLabStatusFacts } from "./gitlab-facts.js";
const GLAB_ENV = {
@@ -112,6 +113,9 @@ export interface CreateGitLabServiceOptions {
runner?: GlabCommandRunner;
resolveGlabPath?: () => Promise<string | null>;
resolveRemoteUrl?: (cwd: string) => Promise<string | null>;
now?: () => number;
watchPollMs?: number;
watchInitialDelayMs?: number;
}
const GitLabPipelineSchema = z
@@ -925,19 +929,37 @@ export function createGitLabService(options: CreateGitLabServiceOptions = {}): F
const resolveGlab = createCachedCliPathResolver(options.resolveGlabPath ?? resolveGlabPath);
const resolveRemoteUrl = options.resolveRemoteUrl ?? defaultResolveRemoteUrl;
async function run(args: string[], runOptions: GlabCommandRunnerOptions): Promise<string> {
async function runRaw(
args: string[],
runOptions: GlabCommandRunnerOptions,
): Promise<GlabCommandResult> {
const glabPath = await resolveGlab();
if (!glabPath) {
throw new GlabCliMissingError();
}
try {
const result = await runner(args, runOptions);
return result.stdout.trim();
return await runner(args, runOptions);
} catch (error) {
throw glabCliRunner.normalizeError(error, { args, cwd: runOptions.cwd });
}
}
async function run(args: string[], runOptions: GlabCommandRunnerOptions): Promise<string> {
const result = await runRaw(args, runOptions);
return result.stdout.trim();
}
const changeRequests = createGitLabChangeRequestSource({
runCommand: runRaw,
isAuthError: (error) => error instanceof GlabAuthenticationError,
isCommandError: (error): error is GlabCommandError => error instanceof GlabCommandError,
createAuthError: (stderr) => new GlabAuthenticationError({ stderr }),
createCommandError: (params) => new GlabCommandError(params),
now: options.now,
pollIntervalMs: options.watchPollMs,
initialDelayMs: options.watchInitialDelayMs,
});
// Centralize parse + validate so a malformed or empty glab payload surfaces as
// a classified GlabCommandError (with args + cwd) instead of a raw
// SyntaxError/ZodError that bypasses the Glab* error classification.
@@ -1486,6 +1508,12 @@ export function createGitLabService(options: CreateGitLabServiceOptions = {}): F
return { success: true };
},
changeRequests,
invalidate(_input: { cwd: string }): void {},
dispose(): void {
changeRequests.dispose();
},
};
}
+138
View File
@@ -0,0 +1,138 @@
import copy from "../src/i18n/resources/en.json" with { type: "json" };
import { expect, test, waitForHydration, type Page } from "./fixtures";
async function openHub(page: Page, width = 1024) {
await page.setViewportSize({ width, height: 900 });
await page.goto("/hub");
await expect(page.getByRole("heading", { name: "Paseo Hub", level: 1 })).toBeVisible();
}
async function tabIntoNextPreview(page: Page) {
await waitForHydration(page);
await page.getByRole("tab", { name: /^Slack/ }).focus();
await page.keyboard.press("ArrowRight");
await page.keyboard.press("Tab");
}
async function readPreviewOnFocus(page: Page) {
return page.getByRole("tabpanel").evaluateHandle((panel) => {
const atFocus = { label: "" };
panel.addEventListener(
"focus",
() => {
atFocus.label = panel.querySelector('[role="img"]')?.getAttribute("aria-label") ?? "";
},
{ once: true },
);
return atFocus;
});
}
async function useLargerText(page: Page) {
await page.addStyleTag({ content: "html { font-size: 125%; }" });
}
async function expectSourceLabelFits(page: Page, name: string, text = name) {
const label = page.getByRole("tab", { name }).getByText(text, { exact: true });
await expect(label).toBeVisible();
expect(await label.evaluate((element) => element.scrollWidth <= element.clientWidth)).toBe(true);
}
async function expectPreviewRowsFit(page: Page, source: string, ...rows: string[]) {
const name = new RegExp(`^${source}`);
await page.getByRole("tab", { name }).click();
const preview = page.getByRole("tabpanel", { name });
await preview.scrollIntoViewIfNeeded();
for (const row of rows) {
const text = preview.getByText(row, { exact: true }).filter({ visible: true });
await expect(text).toBeInViewport({ ratio: 1 });
expect(await text.evaluate((element) => element.scrollWidth <= element.clientWidth)).toBe(true);
}
}
async function focusProSeatHelp(page: Page) {
const pro = page
.getByRole("article")
.filter({ has: page.getByRole("heading", { name: "Pro", exact: true }) });
const help = pro.getByLabel(/^Seats are Hub members/).locator("..");
await help.scrollIntoViewIfNeeded();
await help.focus();
return pro.getByRole("tooltip");
}
test("Hub fits a viewport narrower than its page frame", async ({ page }) => {
await openHub(page);
const { contentWidth, viewportWidth } = await page.evaluate(() => ({
contentWidth: document.documentElement.scrollWidth,
viewportWidth: document.documentElement.clientWidth,
}));
expect(contentWidth).toBeLessThanOrEqual(viewportWidth);
});
for (const width of [320, 768, 1024]) {
test(`the complete Pro seat explanation is visible on keyboard focus at ${width}px`, async ({
page,
}) => {
test.skip(Boolean(process.env.WEBSITE_TEST_URL), "Requires the Hub plans fixture");
await openHub(page, width);
const tooltip = await focusProSeatHelp(page);
await expect(tooltip).toContainText("do not count as seats");
await expect(tooltip).toBeInViewport({ ratio: 1 });
});
}
test("the Slack starter forwards the mention and declares a thread reply", async ({ page }) => {
await openHub(page);
const starter = page.locator("pre").filter({ hasText: "name: slack-help" });
await expect(starter).toContainText("${{ paseo.prompt }}");
await expect(starter).toContainText("hub.reply");
await expect(starter).toContainText("slack.reply:");
});
test("keyboard focus enters the selected preview with its current content", async ({ page }) => {
await openHub(page);
const atFocus = await readPreviewOnFocus(page);
await tabIntoNextPreview(page);
await expect(page.getByRole("tabpanel", { name: /^GitHub/ })).toBeFocused();
expect((await atFocus.jsonValue()).label).toMatch(/^GitHub issue/);
});
test("source names fit on a narrow phone", async ({ page }) => {
await openHub(page, 320);
await expectSourceLabelFits(page, "Schedules");
await expectSourceLabelFits(page, "Webhooks");
});
test("source names remain readable with larger text on a phone", async ({ page }) => {
await openHub(page, 375);
await useLargerText(page);
for (const name of ["GitHub", "Discord", "Schedules", "Webhooks"]) {
await expectSourceLabelFits(page, name);
}
});
test("desktop source descriptions fit with larger text", async ({ page }) => {
await openHub(page, 1280);
await useLargerText(page);
for (const { name, description } of Object.values(copy.hub.sources)) {
await expectSourceLabelFits(page, name, description);
}
});
test("Hub previews have room for their final rows with larger text", async ({ page }) => {
await page.emulateMedia({ reducedMotion: "reduce" });
await openHub(page, 1280);
await useLargerText(page);
await waitForHydration(page);
await expectPreviewRowsFit(page, "GitHub", "Open in Paseo");
await expectPreviewRowsFit(page, "Discord", "Message #engineering");
});
test("preview results fit on a narrow phone with larger text", async ({ page }) => {
await page.emulateMedia({ reducedMotion: "reduce" });
await openHub(page, 320);
await useLargerText(page);
await waitForHydration(page);
await expectPreviewRowsFit(page, "Discord", "Fix stale worktrees", "getpaseo/paseo#2825");
await expectPreviewRowsFit(page, "Schedules", "tests passed");
});
+74
View File
@@ -9,6 +9,12 @@ async function chooseLanguage(page: Page, language: string) {
await page.getByRole("menuitemradio", { name: language }).click();
}
async function selectHubSourceTab(page: Page, name: string | RegExp) {
const tab = page.getByRole("tab", { name });
await tab.click();
await expect(tab).toHaveAttribute("aria-selected", "true");
}
async function withPageScriptsHeld(page: Page, run: (release: () => void) => Promise<void>) {
let releaseScripts!: () => void;
const scriptsReleased = new Promise<void>((resolve) => {
@@ -109,6 +115,74 @@ test("switches language on the same page, keeping the query and then every link"
await expect(page.locator("html")).toHaveAttribute("lang", "en");
});
for (const {
locale,
prefix,
linearTab,
linearDocsLink,
linearTriggerHeading,
linearAppLink,
linearAppHeading,
webhooksTab,
webhooksDocsLink,
webhooksHeading,
} of [
{
locale: "English",
prefix: "",
linearTab: /^Linear\b/,
linearDocsLink: "Read Linear docs",
linearTriggerHeading: "Linear triggers",
linearAppLink: "Linear app",
linearAppHeading: "Linear for Hub",
webhooksTab: /^Webhooks\b/,
webhooksDocsLink: "Read Webhooks docs",
webhooksHeading: "Inbound webhooks",
},
{
locale: "Chinese",
prefix: "/zh-CN",
linearTab: /^Linear\b/,
linearDocsLink: "阅读 Linear 文档",
linearTriggerHeading: "Linear 触发器",
linearAppLink: "Linear 应用",
linearAppHeading: "为 Hub 配置 Linear",
webhooksTab: /^Webhook\b/,
webhooksDocsLink: "阅读 Webhook 文档",
webhooksHeading: "入站 webhook",
},
]) {
test(`navigates from the ${locale} Hub showcase to Linear and Webhook docs`, async ({ page }) => {
await page.goto(`${prefix}/hub`);
await test.step("opens Linear trigger docs and Linear app setup", async () => {
await selectHubSourceTab(page, linearTab);
const triggerLink = page.getByRole("link", { name: linearDocsLink, exact: true });
await expect(triggerLink).toHaveAttribute("href", `${prefix}/docs/hub/triggers/linear`);
await triggerLink.click();
await expect(
page.getByRole("heading", { name: linearTriggerHeading, level: 1 }),
).toBeVisible();
await expect(page.getByText("linear.comment_created", { exact: true }).first()).toBeVisible();
const appLink = page.locator("main").getByRole("link", { name: linearAppLink, exact: true });
await expect(appLink).toHaveAttribute("href", `${prefix}/docs/hub/self-hosting/linear-app`);
await appLink.click();
await expect(page.getByRole("heading", { name: linearAppHeading, level: 1 })).toBeVisible();
});
await test.step("opens Webhooks trigger docs from the Hub showcase", async () => {
await page.goto(`${prefix}/hub`);
await selectHubSourceTab(page, webhooksTab);
const webhookLink = page.getByRole("link", { name: webhooksDocsLink, exact: true });
await expect(webhookLink).toHaveAttribute("href", `${prefix}/docs/hub/triggers/webhooks`);
await webhookLink.click();
await expect(page.getByRole("heading", { name: webhooksHeading, level: 1 })).toBeVisible();
await expect(page.getByText("webhook.received", { exact: true }).first()).toBeVisible();
});
});
}
test("shows the language as an abbreviation and lists every language by name", async ({ page }) => {
await page.goto("/docs/cli#running-agents");
const button = languageButton(page);
+1 -1
View File
@@ -149,7 +149,7 @@ test("the opening scene waits until most of the mockup is on screen", async ({ p
});
test("the opening scene starts in a window shorter than most of the mockup", async ({ page }) => {
await openHomepage(page, { width: 1400, height: 400 });
await openHomepage(page, { width: 1400, height: 320 });
const mockup = page.getByRole("img", { name: desktopName, exact: true });
const request = mockup.getByText("Fix the issues labeled ready, one worktree each.");
await mockup.scrollIntoViewIfNeeded();
+1
View File
@@ -586,6 +586,7 @@ test.describe("registry fixture layout", () => {
] as const) {
await page.setViewportSize({ width, height: 720 });
await page.goto("/plugins/omercnet/dracula");
await expectPageWithinViewport(page);
const three = page.getByRole("link", { name: /^Dracula (screenshot|video) \d$/ });
const shares = await three.evaluateAll(visibleShares);
expect(shares.map((share) => (share > 0.1 && share < 0.5 ? "peeks" : share))).toEqual(
+5
View File
@@ -1,5 +1,6 @@
import { createServer } from "node:http";
import registry from "./registry.fixture.json" with { type: "json" };
import hubPlans from "../src/hub-plans.fixture.json" with { type: "json" };
import securityPlugin from "./overview.fixture.json" with { type: "json" };
@@ -13,6 +14,10 @@ securityPlugin.readme +=
// Serve the published registry contract so SSR and browser navigation use the same data.
createServer((request, response) => {
response.setHeader("Content-Type", "application/json");
if (request.url === "/hub-plans") {
response.end(JSON.stringify(hubPlans));
return;
}
if (request.url === "/index.json") {
response.end(JSON.stringify(registry));
return;
+1
View File
@@ -15,6 +15,7 @@
"@cloudflare/vite-plugin": "^1.29.1",
"@cloudflare/workers-types": "^4.20260317.1",
"@fontsource-variable/geist": "^5.3.0",
"@fontsource-variable/plus-jakarta-sans": "^5.3.0",
"@getpaseo/protocol": "*",
"@tanstack/react-router": "^1.170.16",
"@tanstack/react-start": "^1.168.26",
+1
View File
@@ -31,6 +31,7 @@ export default defineConfig({
),
CLOUDFLARE_INCLUDE_PROCESS_ENV: "true",
PLUGINS_REGISTRY_URL: "http://127.0.0.1:8188",
VITE_HUB_PLANS_URL: "http://127.0.0.1:8188/hub-plans",
},
},
],
@@ -1,8 +1,10 @@
import { useLoaderData } from "@tanstack/react-router";
import { useTranslation } from "react-i18next";
import { LandingPage } from "~/components/landing-page";
import { type AgentPageSlug, getAgentPage } from "~/data/agent-pages";
import { getTranslator, routeLocale } from "~/i18n";
import { pageMeta } from "~/meta";
import { getPluginCount } from "~/plugins";
export function agentRouteOptions(slug: AgentPageSlug) {
return {
@@ -16,10 +18,18 @@ export function agentRouteOptions(slug: AgentPageSlug) {
locale,
});
},
loader: async () => ({ pluginCount: await getPluginCount() }),
component: function AgentLandingPage() {
const { t } = useTranslation();
const data = useLoaderData({ strict: false }) as { pluginCount?: number | null } | undefined;
const page = getAgentPage(slug, t);
return <LandingPage title={page.title} subtitle={page.subtitle} />;
return (
<LandingPage
title={page.title}
subtitle={page.subtitle}
pluginCount={data?.pluginCount ?? null}
/>
);
},
};
}
@@ -45,6 +45,20 @@ export function SlackIcon(props: React.SVGProps<SVGSVGElement>) {
);
}
export function LinearIcon(props: React.SVGProps<SVGSVGElement>) {
return (
<svg
xmlns="http://www.w3.org/2000/svg"
viewBox="0 0 24 24"
fill="currentColor"
aria-hidden="true"
{...props}
>
<path d="M2.886 4.18A11.982 11.982 0 0 1 11.99 0C18.624 0 24 5.376 24 12.009c0 3.64-1.62 6.903-4.18 9.105L2.887 4.18ZM1.817 5.626l16.556 16.556c-.524.33-1.075.62-1.65.866L.951 7.277c.247-.575.537-1.126.866-1.65ZM.322 9.163l14.515 14.515c-.71.172-1.443.282-2.195.322L0 11.358a12 12 0 0 1 .322-2.195Zm-.17 4.862 9.823 9.824a12.02 12.02 0 0 1-9.824-9.824Z" />
</svg>
);
}
export function OpenCollectiveIcon(props: React.SVGProps<SVGSVGElement>) {
return (
<svg
+16 -6
View File
@@ -2,15 +2,25 @@ import type { ReactNode } from "react";
export function FAQItem({ question, children }: { question: string; children: ReactNode }) {
return (
<details className="group">
<summary className="font-medium text-sm cursor-pointer list-none grid grid-cols-[1.25rem_1fr] items-baseline">
<span className="font-mono text-lg leading-none text-white/40 group-open:hidden">+</span>
<span className="font-mono text-lg leading-none text-white/40 hidden group-open:inline">
<details className="group py-5 first:pt-4 last:pb-4">
<summary className="flex cursor-pointer list-none items-baseline justify-between gap-6 text-[15px] font-medium text-white/90 transition-colors hover:text-white">
<span>{question}</span>
<span
aria-hidden="true"
className="shrink-0 font-mono text-base leading-none text-white/40 transition-colors group-hover:text-white/70 group-open:hidden"
>
+
</span>
<span
aria-hidden="true"
className="hidden shrink-0 font-mono text-base leading-none text-accent-text group-open:inline"
>
−
</span>
{question}
</summary>
<div className="text-sm text-muted-foreground space-y-2 mt-2 pl-5 prose">{children}</div>
<div className="prose mt-3 max-w-2xl space-y-2.5 text-sm leading-relaxed text-muted-foreground">
{children}
</div>
</details>
);
}
@@ -0,0 +1,254 @@
import { Check, CornerDownRight, GitPullRequest, Hash, PlusCircle } from "lucide-react";
import { Trans, useTranslation } from "react-i18next";
import { DiscordIcon } from "~/components/brand-icons";
import {
MoAvatar,
MockupStageWindow,
MockupStep,
OpenInPaseoChip,
PaseoBotAvatar,
type SourceMockupProps,
WindowTrafficLights,
} from "./shared";
const DISCORD_CHANNELS = ["general", "engineering", "bugs", "releases"] as const;
const STEP_DELAYS = {
userMention: 0.06,
threadStart: 0.55,
botWorking: 1.05,
botDone: 1.7,
} as const;
const DISCORD_COMPONENTS = {
mention: (
<span className="rounded-[3px] bg-[#5865F2]/30 px-1 py-[0.5px] font-medium text-[#C9CDFB]">
@paseo-bot
</span>
),
host: (
<span className="rounded-[3px] bg-[#1E1F22] px-1.5 py-[1px] font-mono text-[11px] text-[#DBDEE1]" />
),
issue: <span className="font-mono text-[12px] text-[#00A8FC]">#2799</span>,
};
export function DiscordSourceMockup({ active, reduceMotion }: SourceMockupProps) {
const { t } = useTranslation();
return (
<MockupStageWindow
ariaLabel={t("hub.demo.discord.alt")}
active={active}
reduceMotion={reduceMotion}
className="border-[#3F4147] bg-[#313338]"
>
<DiscordChrome />
<div className="grid min-h-0 flex-1 grid-cols-1 md:grid-cols-[164px_minmax(0,1fr)]">
<DiscordSidebar />
<div className="flex min-h-0 min-w-0 flex-col bg-[#313338]">
<DiscordChannelHeader />
<DiscordMessageFeed />
<DiscordComposer />
</div>
</div>
</MockupStageWindow>
);
}
function DiscordMessageFeed() {
const { t } = useTranslation();
return (
<div className="flex-1 space-y-3 px-4 py-3">
<MockupStep delay={STEP_DELAYS.userMention}>
<DiscordMessage author="mo" time={t("hub.demo.discord.time1")}>
<p>
<Trans i18nKey="hub.demo.discord.userPrompt" components={DISCORD_COMPONENTS} />
</p>
</DiscordMessage>
</MockupStep>
<MockupStep
delay={STEP_DELAYS.threadStart}
className="flex items-start gap-2 pl-2 text-[11.5px] text-[#949BA4]"
>
<CornerDownRight className="h-3.5 w-3.5 shrink-0 text-[#949BA4]" aria-hidden="true" />
<p>
<span className="font-medium text-[#F2F3F5]">paseo-bot</span>{" "}
{t("hub.demo.discord.startedThread")}{" "}
<span className="font-semibold text-[#F2F3F5]">{t("hub.demo.discord.threadTitle")}</span>
</p>
</MockupStep>
<div className="ml-3 space-y-3 border-l-2 border-[#4E5058] pl-3.5">
<MockupStep delay={STEP_DELAYS.botWorking}>
<DiscordMessage author="paseo-bot" time={t("hub.demo.discord.time1")} bot>
<p className="text-[#DBDEE1]">
<Trans i18nKey="hub.demo.discord.botStarted" components={DISCORD_COMPONENTS} />
</p>
</DiscordMessage>
</MockupStep>
<MockupStep delay={STEP_DELAYS.botDone}>
<DiscordMessage author="paseo-bot" time={t("hub.demo.discord.time2")} bot>
<p className="text-[#DBDEE1]">{t("hub.demo.discord.botFinished")}</p>
<DiscordPrEmbed />
</DiscordMessage>
</MockupStep>
</div>
</div>
);
}
function DiscordPrEmbed() {
const { t } = useTranslation();
return (
<div className="mt-2 space-y-2">
<div className="rounded-[4px] border-l-[4px] border-[#2BAC76] bg-[#2B2D31] px-3 py-2.5">
<div className="flex items-center gap-1.5 text-[12px] font-semibold text-[#00A8FC]">
<GitPullRequest className="h-3.5 w-3.5 shrink-0 text-[#2BAC76]" aria-hidden="true" />
<span>getpaseo/paseo#2825</span>
</div>
<p className="mt-0.5 text-[12px] text-[#DBDEE1]">
fix(worktree): prune orphaned branches on close
</p>
<div className="mt-2 grid grid-cols-3 gap-2 text-[11px]">
<div>
<p className="font-semibold text-[#B5BAC1]">{t("hub.demo.discord.fieldHost")}</p>
<p className="font-mono text-[#DBDEE1]">devbox</p>
</div>
<div>
<p className="font-semibold text-[#B5BAC1]">{t("hub.demo.discord.fieldDiff")}</p>
<p className="font-mono text-[#DBDEE1]">+46 -12</p>
</div>
<div>
<p className="font-semibold text-[#B5BAC1]">{t("hub.demo.discord.fieldChecks")}</p>
<p className="inline-flex items-center gap-1 text-[#57F287]">
<Check className="h-3 w-3" aria-hidden="true" />
{t("hub.demo.shared.testsPassed")}
</p>
</div>
</div>
</div>
<div>
<OpenInPaseoChip variant="discord" />
</div>
</div>
);
}
function DiscordComposer() {
const { t } = useTranslation();
return (
<div
aria-hidden="true"
className="mx-4 mt-auto mb-3 flex items-center gap-2.5 rounded-[8px] bg-[#383A40] px-3 py-2 text-[12.5px] text-[#80848E]"
>
<PlusCircle className="h-4 w-4 shrink-0 text-[#B5BAC1]" />
<span className="truncate">{t("hub.demo.discord.composerPlaceholder")}</span>
</div>
);
}
function DiscordChrome() {
return (
<div className="flex h-9 shrink-0 items-center justify-between border-b border-[#1E1F22] bg-[#1E1F22] px-3.5">
<div className="flex items-center gap-3">
<WindowTrafficLights />
<span className="text-[12px] font-semibold text-[#B5BAC1]">Discord</span>
</div>
<DiscordIcon className="h-3.5 w-3.5 text-[#5865F2]" />
</div>
);
}
function DiscordSidebar() {
const { t } = useTranslation();
return (
<aside
aria-hidden="true"
className="hidden flex-col border-r border-[#1F2023] bg-[#2B2D31] md:flex"
>
<div className="border-b border-[#1F2023] px-3.5 py-2.5 text-[13.5px] font-bold text-[#F2F3F5]">
Paseo
</div>
<div className="space-y-0.5 px-2 py-3 text-[12.5px]">
<p className="px-2 pb-1 text-[10.5px] font-semibold uppercase tracking-wide text-[#949BA4]">
{t("hub.demo.discord.textChannels")}
</p>
{DISCORD_CHANNELS.map((channel) => (
<div key={channel}>
<div
className={`flex items-center gap-1.5 rounded-[5px] px-2 py-1 ${
channel === "engineering"
? "bg-[#404249] font-medium text-[#F2F3F5]"
: "text-[#949BA4]"
}`}
>
<Hash className="h-3.5 w-3.5 shrink-0 opacity-75" />
<span className="truncate">{channel}</span>
</div>
{channel === "engineering" ? (
<div className="mt-0.5 ml-3 flex items-center gap-1.5 border-l border-[#4E5058] py-1 pl-2 text-[11.5px] text-[#DBDEE1]">
<span className="truncate">{t("hub.demo.discord.threadTitle")}</span>
</div>
) : null}
</div>
))}
</div>
</aside>
);
}
function DiscordChannelHeader() {
const { t } = useTranslation();
return (
<div className="flex shrink-0 items-center justify-between gap-3 border-b border-[#26282C] px-4 py-2">
<div className="flex min-w-0 items-center gap-2">
<Hash className="h-4 w-4 shrink-0 text-[#80848E]" aria-hidden="true" />
<span className="text-[14px] font-semibold text-[#F2F3F5]">engineering</span>
<span className="hidden h-3.5 w-px bg-[#3F4147] sm:inline-block" aria-hidden="true" />
<span className="hidden truncate text-[11.5px] text-[#949BA4] sm:inline">
{t("hub.demo.discord.channelTopic")}
</span>
</div>
</div>
);
}
function DiscordMessage({
author,
time,
bot,
children,
}: {
author: string;
time: string;
bot?: boolean;
children: React.ReactNode;
}) {
const { t } = useTranslation();
return (
<div className="flex items-start gap-2.5">
{bot ? (
<PaseoBotAvatar size="md" rounded="rounded-full" className="mt-0.5" />
) : (
<MoAvatar size="md" rounded="rounded-full" className="mt-0.5" />
)}
<div className="min-w-0 flex-1 space-y-0.5">
<div className="flex flex-wrap items-center gap-1.5">
<span className="text-[13.5px] font-semibold text-[#F2F3F5]">{author}</span>
{bot ? (
<span className="inline-flex items-center gap-0.5 rounded-[3px] bg-[#5865F2] px-1.5 py-[1px] text-[9.5px] font-semibold uppercase tracking-wide text-white">
<Check className="h-2.5 w-2.5" aria-hidden="true" />
{t("hub.demo.shared.appBadge")}
</span>
) : null}
<span className="text-[11px] text-[#949BA4]">{time}</span>
</div>
<div className="text-[13px] leading-[1.45] text-[#DBDEE1]">{children}</div>
</div>
</div>
);
}
@@ -0,0 +1,287 @@
import { Check, CircleDot, GitPullRequest, Tag } from "lucide-react";
import { Trans, useTranslation } from "react-i18next";
import { GitHubIcon } from "~/components/brand-icons";
import {
MoAvatar,
MockupStageWindow,
MockupStep,
OpenInPaseoChip,
PaseoBotAvatar,
type SourceMockupProps,
WindowTrafficLights,
} from "./shared";
const STEP_DELAYS = {
issue: 0.06,
labelEvent: 0.55,
botReply: 1.2,
checks: 1.85,
} as const;
const GH_COMPONENTS = {
mention: <span className="font-semibold text-[#58A6FF]">@paseo-bot</span>,
host: (
<span className="rounded-[4px] border border-[#30363D] bg-[#161B22] px-1.5 py-[1px] font-mono text-[11px] text-[#E6EDF3]" />
),
pr: <span className="font-medium text-[#58A6FF] underline decoration-[#58A6FF]/40" />,
code: (
<code className="rounded-[4px] bg-[#21262D] px-1.5 py-[1px] font-mono text-[11.5px] text-[#E6EDF3]" />
),
};
const CHECK_NAMES = ["typecheck", "vitest", "lint", "build"] as const;
export function GitHubSourceMockup({ active, reduceMotion }: SourceMockupProps) {
const { t } = useTranslation();
return (
<MockupStageWindow
ariaLabel={t("hub.demo.github.alt")}
active={active}
reduceMotion={reduceMotion}
className="border-[#30363D] bg-[#0D1117]"
>
<GitHubChrome />
<GitHubIssueHeader />
<div className="grid min-h-0 flex-1 grid-cols-1 sm:grid-cols-[minmax(0,1fr)_156px]">
<GitHubTimeline />
<GitHubSidebar />
</div>
</MockupStageWindow>
);
}
function GitHubTimeline() {
const { t } = useTranslation();
return (
<div className="relative space-y-3 px-4 py-3.5">
<span
aria-hidden="true"
className="pointer-events-none absolute top-11 bottom-6 left-[27px] w-[2px] bg-[#21262D]"
/>
<MockupStep delay={STEP_DELAYS.issue} className="relative">
<GitHubComment
author="mo"
badge={t("hub.demo.github.authorBadge")}
timestamp={t("hub.demo.github.openedAgo")}
>
<p>
<Trans i18nKey="hub.demo.github.issueBody" components={GH_COMPONENTS} />
</p>
</GitHubComment>
</MockupStep>
<MockupStep
delay={STEP_DELAYS.labelEvent}
className="relative flex items-center gap-2.5 pl-1"
>
<span className="relative z-10 flex h-6 w-6 shrink-0 items-center justify-center rounded-full border border-[#30363D] bg-[#161B22] text-[#8B949E]">
<Tag className="h-3 w-3" aria-hidden="true" />
</span>
<div className="flex flex-wrap items-center gap-1.5 text-[11.5px] text-[#8B949E]">
<span className="font-semibold text-[#E6EDF3]">mo</span>
<span>{t("hub.demo.github.addedLabel")}</span>
<span className="rounded-full border border-[#20744A]/60 bg-[#20744A]/20 px-2 py-[1px] font-mono text-[10.5px] font-medium text-[#6CB17B]">
paseo
</span>
<span>·</span>
<span>{t("hub.demo.github.startedOn")}</span>
</div>
</MockupStep>
<MockupStep delay={STEP_DELAYS.botReply} className="relative">
<GitHubComment
author="paseo-bot"
badge={t("hub.demo.github.botBadge")}
timestamp={t("hub.demo.github.repliedAgo")}
bot
>
<p>
<Trans i18nKey="hub.demo.github.botReply" components={GH_COMPONENTS} />
</p>
<GitHubPrSummaryCard />
</GitHubComment>
</MockupStep>
</div>
);
}
function GitHubPrSummaryCard() {
const { t } = useTranslation();
return (
<MockupStep
delay={STEP_DELAYS.checks}
className="mt-2.5 overflow-hidden rounded-md border border-[#30363D] bg-[#0D1117]"
>
<div className="flex flex-wrap items-center justify-between gap-2 border-b border-[#21262D] bg-[#161B22] px-3 py-2">
<div className="flex min-w-0 items-center gap-1.5">
<GitPullRequest className="h-3.5 w-3.5 shrink-0 text-[#3FB950]" aria-hidden="true" />
<span className="text-[12px] font-semibold text-[#E6EDF3]">
fix(terminal): drain PTY write queue under burst
</span>
<span className="font-mono text-[11px] text-[#8B949E]">#2819</span>
</div>
<span className="shrink-0 font-mono text-[11px]">
<span className="text-[#3FB950]">+84</span> <span className="text-[#F85149]">-19</span>
</span>
</div>
<div className="flex flex-wrap items-center justify-between gap-2 px-3 py-2">
<div className="flex flex-wrap items-center gap-1.5">
<span className="inline-flex items-center gap-1 text-[11.5px] font-medium text-[#3FB950]">
<Check className="h-3.5 w-3.5" aria-hidden="true" />
{t("hub.demo.github.checksPassed")}
</span>
<span className="hidden items-center gap-1 sm:inline-flex">
{CHECK_NAMES.map((name) => (
<span
key={name}
className="rounded border border-[#30363D] bg-[#161B22] px-1.5 py-[1px] font-mono text-[10px] text-[#8B949E]"
>
{name}
</span>
))}
</span>
</div>
<OpenInPaseoChip variant="brand" />
</div>
</MockupStep>
);
}
function GitHubChrome() {
return (
<div className="flex h-9 shrink-0 items-center justify-between border-b border-[#21262D] bg-[#010409] px-3.5">
<div className="flex items-center gap-3">
<WindowTrafficLights />
<div className="flex items-center gap-1.5 text-[12px] text-[#8B949E]">
<GitHubIcon className="h-3.5 w-3.5 text-[#E6EDF3]" />
<span>getpaseo</span>
<span className="text-[#484F58]">/</span>
<span className="font-semibold text-[#E6EDF3]">paseo</span>
</div>
</div>
<div
className="hidden items-center gap-4 text-[11.5px] text-[#8B949E] sm:flex"
aria-hidden="true"
>
<span className="relative py-2 font-medium text-[#E6EDF3]">
Issues
<span className="absolute right-0 -bottom-[3px] left-0 h-[2px] rounded-full bg-[#F78166]" />
</span>
<span>Pull requests</span>
<span>Actions</span>
</div>
</div>
);
}
function GitHubIssueHeader() {
const { t } = useTranslation();
return (
<div className="shrink-0 border-b border-[#21262D] px-4 py-3">
<div className="flex flex-wrap items-baseline gap-x-2 gap-y-1">
<h4 className="text-[15px] font-semibold text-[#E6EDF3]">
{t("hub.demo.github.issueTitle")}
</h4>
<span className="font-mono text-[14px] text-[#8B949E]">#2811</span>
</div>
<div className="mt-1.5 flex flex-wrap items-center gap-2 text-[11.5px] text-[#8B949E]">
<span className="inline-flex items-center gap-1 rounded-full bg-[#238636] px-2.5 py-0.5 text-[11px] font-semibold text-white">
<CircleDot className="h-3 w-3" aria-hidden="true" />
Open
</span>
<span>
<strong className="font-semibold text-[#E6EDF3]">mo</strong>{" "}
{t("hub.demo.github.issueMeta")}
</span>
</div>
</div>
);
}
function GitHubComment({
author,
badge,
timestamp,
bot,
children,
}: {
author: string;
badge: string;
timestamp: string;
bot?: boolean;
children: React.ReactNode;
}) {
return (
<div className="flex items-start gap-2.5">
{bot ? (
<PaseoBotAvatar size="sm" rounded="rounded-full" className="relative z-10 mt-0.5 h-7 w-7" />
) : (
<MoAvatar size="sm" rounded="rounded-full" className="relative z-10 mt-0.5 h-7 w-7" />
)}
<div className="min-w-0 flex-1 overflow-hidden rounded-md border border-[#30363D] bg-[#0D1117]">
<div className="flex flex-wrap items-center justify-between gap-2 border-b border-[#21262D] bg-[#161B22] px-3 py-1.5 text-[11.5px]">
<div className="flex items-center gap-1.5">
<span className="font-semibold text-[#E6EDF3]">{author}</span>
<span className="rounded-full border border-[#30363D] px-1.5 py-[0.5px] text-[10px] font-medium text-[#8B949E]">
{badge}
</span>
</div>
<span className="text-[11px] text-[#8B949E]">{timestamp}</span>
</div>
<div className="px-3 py-2.5 text-[12.5px] leading-[1.5] text-[#C9D1D9]">{children}</div>
</div>
</div>
);
}
function GitHubSidebar() {
const { t } = useTranslation();
return (
<aside
aria-hidden="true"
className="hidden flex-col gap-3.5 border-l border-[#21262D] px-3.5 py-3.5 text-[11.5px] sm:flex"
>
<div className="space-y-1.5 border-b border-[#21262D] pb-3">
<p className="font-medium text-[#8B949E]">{t("hub.demo.github.assignees")}</p>
<div className="flex items-center gap-1.5 text-[#E6EDF3]">
<PaseoBotAvatar size="xs" rounded="rounded-full" />
<span className="font-medium">paseo-bot</span>
</div>
</div>
<div className="space-y-1.5 border-b border-[#21262D] pb-3">
<p className="font-medium text-[#8B949E]">{t("hub.demo.github.labels")}</p>
<div className="flex flex-wrap gap-1">
<span className="rounded-full border border-[#F85149]/40 bg-[#F85149]/15 px-2 py-[1px] text-[10.5px] font-medium text-[#FF7B72]">
bug
</span>
<span className="rounded-full border border-[#D29922]/40 bg-[#D29922]/15 px-2 py-[1px] text-[10.5px] font-medium text-[#E3B341]">
p0
</span>
<span className="rounded-full border border-[#20744A]/60 bg-[#20744A]/20 px-2 py-[1px] text-[10.5px] font-medium text-[#6CB17B]">
paseo
</span>
</div>
</div>
<div className="space-y-1.5 border-b border-[#21262D] pb-3">
<p className="font-medium text-[#8B949E]">{t("hub.demo.github.development")}</p>
<div className="flex items-center gap-1.5 text-[#58A6FF]">
<GitPullRequest className="h-3.5 w-3.5 shrink-0 text-[#3FB950]" />
<span className="font-mono text-[11.5px]">#2819</span>
</div>
</div>
<div className="space-y-1">
<p className="font-medium text-[#8B949E]">{t("hub.demo.github.daemon")}</p>
<span className="inline-block rounded border border-[#30363D] bg-[#161B22] px-1.5 py-0.5 font-mono text-[11px] text-[#E6EDF3]">
macbook-pro
</span>
</div>
</aside>
);
}
@@ -0,0 +1,231 @@
import { useInView, useReducedMotion } from "framer-motion";
import { ArrowRight } from "lucide-react";
import * as React from "react";
import { useTranslation } from "react-i18next";
import {
HUB_TRIGGER_SOURCES,
type HubTriggerSource,
type HubTriggerSourceId,
} from "~/components/hub-flow";
import { useLocalizePath } from "~/i18n";
import { DiscordSourceMockup } from "./discord-mockup";
import { GitHubSourceMockup } from "./github-mockup";
import { LinearSourceMockup } from "./linear-mockup";
import { SchedulesSourceMockup } from "./schedules-mockup";
import type { SourceMockupProps } from "./shared";
import { SlackSourceMockup } from "./slack-mockup";
import { WebhooksSourceMockup } from "./webhooks-mockup";
const SHOWCASE_ORDER: readonly HubTriggerSourceId[] = [
"slack",
"github",
"linear",
"discord",
"schedules",
"webhooks",
];
const SOURCE_DOC_PATHS: Record<HubTriggerSourceId, string> = {
slack: "/docs/hub/triggers/slack",
github: "/docs/hub/triggers/github",
linear: "/docs/hub/triggers/linear",
discord: "/docs/hub/triggers/discord",
schedules: "/docs/hub/triggers/schedules",
webhooks: "/docs/hub/triggers/webhooks",
};
const SHOWCASE_SOURCES: readonly HubTriggerSource[] = SHOWCASE_ORDER.map((id) => {
const source = HUB_TRIGGER_SOURCES.find((item) => item.id === id);
if (!source) {
throw new Error(`Missing Hub trigger source metadata for "${id}"`);
}
return source;
});
const SOURCE_MOCKUPS: Record<HubTriggerSourceId, React.ComponentType<SourceMockupProps>> = {
slack: SlackSourceMockup,
github: GitHubSourceMockup,
linear: LinearSourceMockup,
discord: DiscordSourceMockup,
schedules: SchedulesSourceMockup,
webhooks: WebhooksSourceMockup,
};
const STAGE_IN_VIEW_OPTIONS = { once: true, margin: "-60px" } as const;
const PANEL_ID = "hub-source-panel";
/**
* Interactive split showcase for Paseo Hub automation sources:
* left clickable pills on desktop (compact pill grid on mobile) paired with a fixed-height
* right stage that swaps between authentic, animated dark-mode mockups with zero layout shift.
*/
export function HubAutomationsShowcase() {
const { t } = useTranslation();
const localize = useLocalizePath();
const reduceMotion = useReducedMotion() === true;
const [selected, setSelected] = React.useState<HubTriggerSourceId>("slack");
const stageRef = React.useRef<HTMLDivElement | null>(null);
const tabRefs = React.useRef<Partial<Record<HubTriggerSourceId, HTMLButtonElement | null>>>({});
const isInView = useInView(stageRef, STAGE_IN_VIEW_OPTIONS);
const ActiveMockup = SOURCE_MOCKUPS[selected];
const registerTabRef = React.useCallback(
(id: HubTriggerSourceId, node: HTMLButtonElement | null) => {
tabRefs.current[id] = node;
},
[],
);
const handleNavigate = React.useCallback((index: number, key: string): boolean => {
let nextIndex: number | null = null;
if (key === "ArrowDown" || key === "ArrowRight") {
nextIndex = (index + 1) % SHOWCASE_SOURCES.length;
} else if (key === "ArrowUp" || key === "ArrowLeft") {
nextIndex = (index - 1 + SHOWCASE_SOURCES.length) % SHOWCASE_SOURCES.length;
} else if (key === "Home") {
nextIndex = 0;
} else if (key === "End") {
nextIndex = SHOWCASE_SOURCES.length - 1;
}
if (nextIndex === null) return false;
const nextId = SHOWCASE_SOURCES[nextIndex].id;
setSelected(nextId);
tabRefs.current[nextId]?.focus();
return true;
}, []);
return (
<div className="grid items-start gap-6 lg:grid-cols-[292px_minmax(0,1fr)] lg:gap-6">
<div className="space-y-2.5">
<div
role="tablist"
aria-label={t("hub.demo.shared.tablistLabel")}
className="grid grid-cols-2 gap-1.5 min-[375px]:grid-cols-3 sm:gap-2 lg:flex lg:flex-col lg:gap-1.5"
>
{SHOWCASE_SOURCES.map((source, index) => (
<SourceTabButton
key={source.id}
source={source}
index={index}
isSelected={source.id === selected}
onSelect={setSelected}
onNavigate={handleNavigate}
registerRef={registerTabRef}
/>
))}
</div>
<p className="text-xs text-muted-foreground lg:hidden">
{t(`hub.sources.${selected}.description`)}
</p>
</div>
<figure ref={stageRef} className="min-w-0 space-y-3">
<div
role="tabpanel"
id={PANEL_ID}
aria-labelledby={`hub-source-tab-${selected}`}
tabIndex={0}
className="relative focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-accent-text lg:h-[33rem]"
>
<ActiveMockup active={isInView} reduceMotion={reduceMotion} />
</div>
<figcaption className="flex flex-wrap items-baseline justify-between gap-x-4 gap-y-1.5 min-h-[1.25rem] text-sm text-muted-foreground">
<span>{t(`hub.demo.${selected}.caption`)}</span>
<a
href={localize(SOURCE_DOC_PATHS[selected])}
className="inline-flex shrink-0 items-center gap-1.5 text-sm text-white/75 transition-colors hover:text-accent-text"
>
{t("hub.demo.shared.docsLink", { source: t(`hub.sources.${selected}.name`) })}
<ArrowRight className="h-3.5 w-3.5" aria-hidden="true" />
</a>
</figcaption>
</figure>
</div>
);
}
function SourceTabButton({
source,
index,
isSelected,
onSelect,
onNavigate,
registerRef,
}: {
source: HubTriggerSource;
index: number;
isSelected: boolean;
onSelect: (id: HubTriggerSourceId) => void;
onNavigate: (index: number, key: string) => boolean;
registerRef: (id: HubTriggerSourceId, node: HTMLButtonElement | null) => void;
}) {
const { t } = useTranslation();
const { id, Icon } = source;
const setRef = React.useCallback(
(node: HTMLButtonElement | null) => {
registerRef(id, node);
},
[id, registerRef],
);
const handleClick = React.useCallback(() => {
onSelect(id);
}, [id, onSelect]);
const handleKeyDown = React.useCallback(
(event: React.KeyboardEvent<HTMLButtonElement>) => {
if (onNavigate(index, event.key)) {
event.preventDefault();
}
},
[index, onNavigate],
);
return (
<button
ref={setRef}
type="button"
role="tab"
id={`hub-source-tab-${id}`}
aria-selected={isSelected}
aria-controls={PANEL_ID}
tabIndex={isSelected ? 0 : -1}
onClick={handleClick}
onKeyDown={handleKeyDown}
className={`group flex min-h-[42px] cursor-pointer items-center justify-center gap-2 rounded-xl border px-2.5 py-2 text-left transition-colors focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-accent-text lg:min-h-0 lg:items-start lg:justify-start lg:gap-3 lg:px-3.5 lg:py-3 ${
isSelected
? "border-brand-green/55 bg-brand-green/[0.13] text-white"
: "border-white/[0.07] bg-white/[0.015] text-white/70 hover:border-white/[0.14] hover:bg-white/[0.035] hover:text-white/90 lg:border-transparent lg:bg-transparent"
}`}
>
<span
className={`shrink-0 transition-colors lg:mt-0.5 ${
isSelected ? "text-accent-text" : "text-white/55 group-hover:text-white/80"
}`}
>
<Icon className="h-4 w-4 lg:h-[18px] lg:w-[18px]" />
</span>
<span className="min-w-0 flex-1">
<span
className={`block text-xs leading-5 font-medium wrap-anywhere lg:text-sm ${
isSelected ? "text-white" : "text-white/80 group-hover:text-white"
}`}
>
{t(`hub.sources.${id}.name`)}
</span>
<span
className={`mt-0.5 hidden text-xs leading-4 wrap-anywhere lg:block ${
isSelected ? "text-white/65" : "text-muted-foreground"
}`}
>
{t(`hub.sources.${id}.description`)}
</span>
</span>
</button>
);
}
@@ -0,0 +1 @@
export { HubAutomationsShowcase } from "./hub-automations-showcase";
@@ -0,0 +1,242 @@
import { Check, ChevronRight, GitPullRequest, SignalHigh } from "lucide-react";
import { Trans, useTranslation } from "react-i18next";
import { LinearIcon } from "~/components/brand-icons";
import {
MoAvatar,
MockupStageWindow,
MockupStep,
OpenInPaseoChip,
PaseoBotAvatar,
type SourceMockupProps,
WindowTrafficLights,
} from "./shared";
const STEP_DELAYS = {
assigned: 0.08,
running: 0.65,
comment: 1.35,
} as const;
const LINEAR_COMPONENTS = {
host: (
<span className="rounded bg-[#22252E] px-1.5 py-[1px] font-mono text-[11px] text-[#E3E6F0]" />
),
code: (
<code className="rounded bg-[#22252E] px-1.5 py-[1px] font-mono text-[11px] text-[#C5CCDF]" />
),
};
export function LinearSourceMockup({ active, reduceMotion }: SourceMockupProps) {
const { t } = useTranslation();
return (
<MockupStageWindow
ariaLabel={t("hub.demo.linear.alt")}
active={active}
reduceMotion={reduceMotion}
className="border-[#262932] bg-[#111318]"
>
<LinearChrome />
<div className="grid min-h-0 flex-1 grid-cols-1 sm:grid-cols-[minmax(0,1fr)_172px]">
<LinearIssuePane />
<LinearPropertiesSidebar />
</div>
</MockupStageWindow>
);
}
function LinearIssuePane() {
const { t } = useTranslation();
return (
<div className="flex min-h-0 flex-col px-5 py-4">
<div className="space-y-1.5 border-b border-[#22252E] pb-3.5">
<p className="font-mono text-[11.5px] text-[#8A8F9E]">PAS-418</p>
<h4 className="text-[16px] font-semibold tracking-[-0.01em] text-[#F1F3F8]">
{t("hub.demo.linear.issueTitle")}
</h4>
<p className="text-[12.5px] leading-relaxed text-[#9DA3B4]">
{t("hub.demo.linear.issueDescription")}
</p>
</div>
<LinearActivityFeed />
</div>
);
}
function LinearActivityFeed() {
const { t } = useTranslation();
return (
<div className="mt-3.5 flex-1 space-y-3">
<p className="text-[11px] font-medium uppercase tracking-wider text-[#6D7385]">
{t("hub.demo.linear.activity")}
</p>
<MockupStep
delay={STEP_DELAYS.assigned}
className="flex items-center gap-2 text-[12px] text-[#9DA3B4]"
>
<MoAvatar size="xs" rounded="rounded-full" />
<span className="min-w-0">
<strong className="font-medium text-[#ECEEF4]">mo</strong>{" "}
{t("hub.demo.linear.assignedEvent")}{" "}
<strong className="font-medium text-[#ECEEF4]">paseo-bot</strong>
</span>
<span className="ml-auto shrink-0 text-[11px] text-[#6D7385]">11m</span>
</MockupStep>
<LinearRunStatusRow />
<LinearBotCommentCard />
</div>
);
}
function LinearRunStatusRow() {
const { t } = useTranslation();
return (
<MockupStep
delay={STEP_DELAYS.running}
className="flex items-center gap-2.5 rounded-lg border border-[#242834] bg-[#171A21] px-3 py-2 text-[12px]"
>
<PaseoBotAvatar size="sm" rounded="rounded-full" />
<div className="min-w-0 flex-1">
<div className="flex flex-wrap items-center gap-1.5">
<span className="font-medium text-[#ECEEF4]">paseo-bot</span>
<span className="text-[#6D7385]">·</span>
<span className="text-[#9DA3B4]">
<Trans i18nKey="hub.demo.linear.runningOn" components={LINEAR_COMPONENTS} />
</span>
</div>
<p className="mt-0.5 font-mono text-[11px] wrap-anywhere text-[#7D8599]">
{t("hub.demo.linear.traceLine")}
</p>
</div>
<Check className="h-3.5 w-3.5 shrink-0 text-[#6CB17B]" aria-hidden="true" />
</MockupStep>
);
}
function LinearBotCommentCard() {
const { t } = useTranslation();
return (
<MockupStep
delay={STEP_DELAYS.comment}
className="rounded-lg border border-[#262A36] bg-[#161820] p-3.5"
>
<div className="flex items-center justify-between gap-2">
<div className="flex items-center gap-2">
<PaseoBotAvatar size="sm" rounded="rounded-full" />
<span className="text-[12.5px] font-semibold text-[#F1F3F8]">paseo-bot</span>
<span className="rounded bg-[#252936] px-1.5 py-[1px] text-[10px] font-medium uppercase tracking-wide text-[#9DA3B4]">
{t("hub.demo.shared.appBadge")}
</span>
</div>
<span className="text-[11px] text-[#6D7385]">6m</span>
</div>
<p className="mt-2 text-[12.5px] leading-[1.5] text-[#C5CCDF]">
<Trans i18nKey="hub.demo.linear.botSummary" components={LINEAR_COMPONENTS} />
</p>
<div className="mt-3 flex flex-wrap items-center justify-between gap-2 border-t border-[#242834] pt-2.5">
<span className="inline-flex items-center gap-1.5 rounded-md border border-[#2A2F3D] bg-[#1C1F2A] px-2 py-1 font-mono text-[11px] text-[#C5CCDF]">
<GitPullRequest className="h-3 w-3 text-[#6CB17B]" aria-hidden="true" />
<span>#2822</span>
<span className="text-[#6CB17B]">· {t("hub.demo.shared.testsPassed")}</span>
</span>
<OpenInPaseoChip variant="brand" />
</div>
</MockupStep>
);
}
function LinearChrome() {
return (
<div className="flex h-9 shrink-0 items-center justify-between border-b border-[#22252E] bg-[#15171E] px-3.5">
<div className="flex items-center gap-3">
<WindowTrafficLights />
<div className="flex items-center gap-1 text-[11.5px] text-[#8A8F9E]">
<LinearIcon className="h-3.5 w-3.5 text-[#5E6AD2]" />
<span>Paseo</span>
<ChevronRight className="h-3 w-3 text-[#555B6E]" aria-hidden="true" />
<span>Core</span>
<ChevronRight className="h-3 w-3 text-[#555B6E]" aria-hidden="true" />
<span className="font-mono text-[#E3E6F0]">PAS-418</span>
</div>
</div>
<span className="hidden rounded-full border border-[#5E6AD2]/35 bg-[#5E6AD2]/15 px-2 py-0.5 text-[10.5px] font-medium text-[#A4ACEE] sm:inline-block">
Cycle 14
</span>
</div>
);
}
function LinearPropertiesSidebar() {
const { t } = useTranslation();
return (
<aside
aria-hidden="true"
className="hidden flex-col gap-3.5 border-l border-[#22252E] bg-[#13151B] px-3.5 py-4 text-[11.5px] sm:flex"
>
<p className="text-[11px] font-medium text-[#6D7385]">{t("hub.demo.linear.properties")}</p>
<LinearPropRow label={t("hub.demo.linear.status")}>
<span className="inline-flex items-center gap-1.5 text-[#ECEEF4]">
<span className="h-2.5 w-2.5 rounded-full border-2 border-[#6CB17B] bg-[#6CB17B]/35" />
<span>In Review</span>
</span>
</LinearPropRow>
<LinearPropRow label={t("hub.demo.linear.priority")}>
<span className="inline-flex items-center gap-1.5 text-[#ECEEF4]">
<SignalHigh className="h-3.5 w-3.5 text-[#F2994A]" />
<span>High</span>
</span>
</LinearPropRow>
<LinearPropRow label={t("hub.demo.linear.assignee")}>
<span className="inline-flex items-center gap-1.5 text-[#ECEEF4]">
<PaseoBotAvatar size="xs" rounded="rounded-full" />
<span>paseo-bot</span>
</span>
</LinearPropRow>
<LinearPropRow label={t("hub.demo.linear.creator")}>
<span className="inline-flex items-center gap-1.5 text-[#ECEEF4]">
<MoAvatar size="xs" rounded="rounded-full" />
<span>mo</span>
</span>
</LinearPropRow>
<LinearPropRow label={t("hub.demo.linear.labels")}>
<div className="flex flex-wrap gap-1">
<span className="inline-flex items-center gap-1 rounded-full border border-[#2A2F3D] bg-[#1A1D26] px-2 py-[1px] text-[10.5px] text-[#C5CCDF]">
<span className="h-1.5 w-1.5 rounded-full bg-[#5E6AD2]" />
mobile
</span>
<span className="inline-flex items-center gap-1 rounded-full border border-[#2A2F3D] bg-[#1A1D26] px-2 py-[1px] text-[10.5px] text-[#C5CCDF]">
<span className="h-1.5 w-1.5 rounded-full bg-[#6CB17B]" />
relay
</span>
</div>
</LinearPropRow>
<LinearPropRow label={t("hub.demo.linear.daemon")}>
<span className="rounded border border-[#2A2F3D] bg-[#1A1D26] px-1.5 py-0.5 font-mono text-[10.5px] text-[#C5CCDF]">
devbox
</span>
</LinearPropRow>
</aside>
);
}
function LinearPropRow({ label, children }: { label: string; children: React.ReactNode }) {
return (
<div className="space-y-1">
<p className="text-[10.5px] text-[#6D7385]">{label}</p>
<div>{children}</div>
</div>
);
}
@@ -0,0 +1,208 @@
import { Check, Clock, GitPullRequest, Hash, TrendingDown } from "lucide-react";
import { Trans, useTranslation } from "react-i18next";
import {
MockupStageWindow,
MockupStep,
OpenInPaseoChip,
PaseoBotAvatar,
type SourceMockupProps,
WindowTrafficLights,
} from "./shared";
import { SlackColorMark } from "./slack-mockup";
const STEP_DELAYS = {
triggered: 0.06,
prOpened: 0.7,
slackDigest: 1.4,
} as const;
const SCHEDULE_COMPONENTS = {
code: (
<code className="rounded bg-white/[0.07] px-1.5 py-[1px] font-mono text-[11px] text-white/90" />
),
pr: <span className="font-medium text-[#1D9BD1] underline decoration-[#1D9BD1]/40" />,
strong: <strong className="font-semibold text-white" />,
};
export function SchedulesSourceMockup({ active, reduceMotion }: SourceMockupProps) {
const { t } = useTranslation();
return (
<MockupStageWindow
ariaLabel={t("hub.demo.schedules.alt")}
active={active}
reduceMotion={reduceMotion}
className="border-white/[0.1] bg-[#121716]"
>
<ScheduleChrome />
<ScheduleHeaderBar />
<div className="flex flex-1 flex-col justify-between gap-3 px-4 py-3.5">
<ScheduleStepsList />
<ScheduleImpactMetrics />
<ScheduleSlackDigestCard />
</div>
</MockupStageWindow>
);
}
function ScheduleChrome() {
const { t } = useTranslation();
return (
<div className="flex min-h-9 shrink-0 items-center justify-between gap-2 border-b border-white/[0.07] bg-[#0D1211] px-3.5 py-1">
<div className="flex min-w-0 items-center gap-3">
<WindowTrafficLights />
<div className="flex min-w-0 items-center gap-1.5 font-mono text-[11.5px] text-white/65">
<Clock className="h-3.5 w-3.5 shrink-0 text-accent-text" aria-hidden="true" />
<span className="wrap-anywhere">.paseo/triggers/daily-ci-optimizer.yml</span>
</div>
</div>
<span className="inline-flex shrink-0 items-center gap-1.5 rounded-full border border-brand-green/50 bg-brand-green/20 px-2 py-0.5 text-[10.5px] font-medium text-accent-text">
<span className="h-1.5 w-1.5 rounded-full bg-[#35C264]" />
{t("hub.demo.schedules.active")}
</span>
</div>
);
}
function ScheduleHeaderBar() {
const { t } = useTranslation();
return (
<div className="flex shrink-0 flex-wrap items-center justify-between gap-2 border-b border-white/[0.07] bg-white/[0.02] px-4 py-2.5">
<div>
<h4 className="text-[14px] font-semibold text-white/95">
{t("hub.demo.schedules.jobTitle")}
</h4>
<p className="text-[11.5px] text-white/55">{t("hub.demo.schedules.cadence")}</p>
</div>
<div className="flex flex-wrap items-center gap-1.5 font-mono text-[11px]">
<span className="rounded border border-white/10 bg-[#0D1211] px-2 py-0.5 text-accent-text">
0 7 * * 1-5
</span>
<span className="rounded border border-white/10 bg-[#0D1211] px-2 py-0.5 text-white/70">
devbox · Claude Code
</span>
</div>
</div>
);
}
function ScheduleStepsList() {
const { t } = useTranslation();
return (
<div className="space-y-3">
<MockupStep delay={STEP_DELAYS.triggered} className="flex items-start gap-2.5">
<span className="mt-0.5 flex h-6 w-6 shrink-0 items-center justify-center rounded-full border border-brand-green/45 bg-brand-green/15 text-accent-text">
<Check className="h-3.5 w-3.5" aria-hidden="true" />
</span>
<div className="min-w-0 flex-1">
<div className="flex items-center justify-between gap-2 text-[12px]">
<span className="font-medium text-white/90">{t("hub.demo.schedules.step1Title")}</span>
<span className="font-mono text-[11px] text-white/40">7:00 AM</span>
</div>
<p className="mt-0.5 text-[12px] leading-relaxed text-white/65">
<Trans i18nKey="hub.demo.schedules.step1Detail" components={SCHEDULE_COMPONENTS} />
</p>
</div>
</MockupStep>
<MockupStep delay={STEP_DELAYS.prOpened} className="flex items-start gap-2.5">
<span className="mt-0.5 flex h-6 w-6 shrink-0 items-center justify-center rounded-full border border-brand-green/45 bg-brand-green/15 text-accent-text">
<GitPullRequest className="h-3.5 w-3.5" aria-hidden="true" />
</span>
<div className="min-w-0 flex-1">
<div className="flex items-center justify-between gap-2 text-[12px]">
<span className="font-medium text-white/90">{t("hub.demo.schedules.step2Title")}</span>
<span className="font-mono text-[11px] text-white/40">7:04 AM</span>
</div>
<SchedulePrPill />
</div>
</MockupStep>
</div>
);
}
function SchedulePrPill() {
const { t } = useTranslation();
return (
<div className="mt-1.5 flex flex-wrap items-center justify-between gap-2 rounded-lg border border-white/[0.08] bg-[#171E1D] px-3 py-2">
<div className="flex min-w-0 items-center gap-1.5 text-[12px]">
<span className="font-medium text-white/90">
perf(ci): cache cargo target & stabilize e2e wait
</span>
<span className="font-mono text-[11px] text-white/45">#2831</span>
</div>
<div className="flex min-w-0 flex-wrap items-center gap-1.5 font-mono text-[10.5px]">
<span className="inline-flex items-center gap-1 rounded bg-[#2BAC76]/15 px-1.5 py-0.5 text-[#6CB17B]">
<TrendingDown className="h-3 w-3" aria-hidden="true" />
CI -38%
</span>
<span className="inline-flex items-center gap-1 rounded border border-white/10 bg-white/[0.04] px-1.5 py-0.5 text-white/70">
<Check className="h-3 w-3 text-[#6CB17B]" aria-hidden="true" />
{t("hub.demo.shared.testsPassed")}
</span>
</div>
</div>
);
}
function ScheduleImpactMetrics() {
const { t } = useTranslation();
return (
<MockupStep
delay={1.05}
className="grid grid-cols-3 divide-x divide-white/[0.07] overflow-hidden rounded-lg border border-white/[0.07] bg-white/[0.02]"
>
<div className="px-3 py-2">
<p className="text-[10.5px] text-white/45">{t("hub.demo.schedules.metricRuntime")}</p>
<p className="mt-0.5 font-mono text-[12px] font-medium text-accent-text">7m 12s → 4m 28s</p>
</div>
<div className="px-3 py-2">
<p className="text-[10.5px] text-white/45">{t("hub.demo.schedules.metricFlake")}</p>
<p className="mt-0.5 font-mono text-[12px] font-medium text-accent-text">18% → 0%</p>
</div>
<div className="px-3 py-2">
<p className="text-[10.5px] text-white/45">{t("hub.demo.schedules.metricCache")}</p>
<p className="mt-0.5 font-mono text-[12px] font-medium text-white/85">94% hit</p>
</div>
</MockupStep>
);
}
function ScheduleSlackDigestCard() {
const { t } = useTranslation();
return (
<MockupStep
delay={STEP_DELAYS.slackDigest}
className="overflow-hidden rounded-lg border border-[#35373B] bg-[#1A1D21]"
>
<div className="flex items-center justify-between border-b border-[#2C2D30] bg-[#14161A] px-3 py-1.5 text-[11px] text-[#ABABAD]">
<span className="inline-flex items-center gap-1.5 font-medium text-[#E5E7EB]">
<SlackColorMark className="h-3 w-3" />
<Hash className="h-3 w-3 text-[#ABABAD]" aria-hidden="true" />
engineering
</span>
<span>{t("hub.demo.schedules.slackPosted")}</span>
</div>
<div className="flex items-start gap-2.5 px-3.5 py-3">
<PaseoBotAvatar size="sm" className="mt-0.5 h-8 w-8" />
<div className="min-w-0 flex-1 space-y-1.5">
<div className="flex items-center gap-1.5">
<span className="text-[13px] font-bold text-[#F8F8F8]">paseo-bot</span>
<span className="rounded-[3px] bg-[#2C2D30] px-1.5 py-[1px] text-[9.5px] font-semibold uppercase tracking-wide text-[#ABABAD]">
{t("hub.demo.shared.appBadge")}
</span>
<span className="text-[11px] text-[#ABABAD]">7:05 AM</span>
</div>
<p className="text-[12.5px] leading-[1.45] text-[#D1D2D3]">
<Trans i18nKey="hub.demo.schedules.slackSummary" components={SCHEDULE_COMPONENTS} />
</p>
<div className="flex flex-wrap items-center gap-2 pt-0.5">
<OpenInPaseoChip variant="slack" />
<span className="text-[11px] text-[#ABABAD]">{t("hub.demo.schedules.notifiedMo")}</span>
</div>
</div>
</div>
</MockupStep>
);
}
@@ -0,0 +1,165 @@
import { motion, type Variants } from "framer-motion";
import type * as React from "react";
import { useTranslation } from "react-i18next";
import { PaseoMark } from "~/components/paseo-brand";
export interface SourceMockupProps {
/** Whether the section is visible or reduced motion is requested. */
active: boolean;
reduceMotion: boolean;
}
export const STEP_VARIANTS: Variants = {
hidden: { opacity: 0, y: 6 },
shown: (delay: number) => ({
opacity: 1,
y: 0,
transition: { delay, duration: 0.32, ease: "easeOut" },
}),
};
type AvatarSize = "xs" | "sm" | "md";
const AVATAR_DIM: Record<AvatarSize, string> = {
xs: "h-4 w-4",
sm: "h-6 w-6",
md: "h-8 w-8 sm:h-9 sm:w-9",
};
const AVATAR_PX: Record<AvatarSize, number> = {
xs: 16,
sm: 24,
md: 36,
};
const BOT_ICON_DIM: Record<AvatarSize, string> = {
xs: "h-2.5 w-2.5",
sm: "h-3.5 w-3.5",
md: "h-4 w-4 sm:h-5 sm:w-5",
};
type OpenChipVariant = "brand" | "slack" | "discord" | "subtle";
const OPEN_CHIP_STYLES: Record<OpenChipVariant, string> = {
brand: "bg-[#20744A] text-white",
slack: "bg-[#007A5A] text-white",
discord: "bg-[#248046] text-white",
subtle: "border border-brand-green/50 bg-brand-green/20 text-[#9FE0B0]",
};
export function MockupStep({
delay,
className,
children,
}: {
delay: number;
className?: string;
children: React.ReactNode;
}) {
return (
<motion.div variants={STEP_VARIANTS} custom={delay} className={className}>
{children}
</motion.div>
);
}
/**
* Animated root container for a single source mockup. Keeps outer dimensions locked to the stage
* so switching tabs or stepping through animations never shifts page layout.
*/
export function MockupStageWindow({
ariaLabel,
active,
reduceMotion,
className = "",
children,
}: {
ariaLabel: string;
active: boolean;
reduceMotion: boolean;
className?: string;
children: React.ReactNode;
}) {
return (
<motion.div
role="img"
aria-label={ariaLabel}
initial={reduceMotion ? "shown" : "hidden"}
animate={reduceMotion || active ? "shown" : "hidden"}
className={`flex h-full flex-col overflow-hidden rounded-xl border wrap-anywhere shadow-[0_24px_64px_-24px_rgba(0,0,0,0.75)] ${className}`}
>
{children}
</motion.div>
);
}
/** Mo's photo avatar used consistently across all source mockups. */
export function MoAvatar({
size = "md",
rounded = "rounded-[6px]",
className = "",
}: {
size?: AvatarSize;
rounded?: string;
className?: string;
}) {
const px = AVATAR_PX[size];
return (
<img
src="/9viSwGkz_400x400.jpg"
alt=""
width={px}
height={px}
loading="lazy"
decoding="async"
className={`shrink-0 object-cover ${AVATAR_DIM[size]} ${rounded} ${className}`}
/>
);
}
/**
* Paseo bot avatar using the canonical Paseo butterfly mark (`PaseoMark`).
* Used consistently for `paseo-bot` across Slack, GitHub, Linear, Discord, Schedules, and Webhooks.
*/
export function PaseoBotAvatar({
size = "md",
rounded = "rounded-[6px]",
className = "",
}: {
size?: AvatarSize;
rounded?: string;
className?: string;
}) {
return (
<span
aria-hidden="true"
className={`inline-flex shrink-0 items-center justify-center border border-white/14 bg-[#101615] ${AVATAR_DIM[size]} ${rounded} ${className}`}
>
<PaseoMark className={`${BOT_ICON_DIM[size]} text-white`} />
</span>
);
}
/** Consistent "Open in Paseo" action chip rendered inside source mockups. */
export function OpenInPaseoChip({ variant = "brand" }: { variant?: OpenChipVariant }) {
const { t } = useTranslation();
return (
<span
className={`inline-flex items-center gap-1.5 rounded-[5px] px-2.5 py-1 text-[11.5px] font-medium ${OPEN_CHIP_STYLES[variant]}`}
>
<PaseoMark className="h-3.5 w-3.5 shrink-0 text-current" />
<span>{t("hub.demo.shared.openInPaseo")}</span>
</span>
);
}
/** macOS-style window traffic lights for desktop-style mockup headers. */
export function WindowTrafficLights() {
return (
<div className="flex items-center gap-1.5" aria-hidden="true">
<span className="h-2.5 w-2.5 rounded-full bg-[#FF5F57]/85" />
<span className="h-2.5 w-2.5 rounded-full bg-[#FEBC2E]/85" />
<span className="h-2.5 w-2.5 rounded-full bg-[#28C840]/85" />
</div>
);
}
@@ -0,0 +1,380 @@
import { motion, type Variants } from "framer-motion";
import {
AtSign,
Check,
ChevronDown,
ChevronLeft,
ChevronRight,
Code,
GitPullRequest,
Hash,
Plus,
Search,
SendHorizontal,
SquarePen,
} from "lucide-react";
import type { ReactNode } from "react";
import { Trans, useTranslation } from "react-i18next";
import { PaseoMark } from "~/components/paseo-brand";
import {
MoAvatar,
MockupStageWindow,
MockupStep,
OpenInPaseoChip,
PaseoBotAvatar,
type SourceMockupProps,
WindowTrafficLights,
} from "./shared";
const DEMO_ISSUES = [
{ id: "#2811", title: "Terminal output drops under load" },
{ id: "#2804", title: "Relay reconnect loop on Android after sleep" },
{ id: "#2799", title: "Worktree cleanup leaves stale branches" },
] as const;
const SIDEBAR_CHANNELS = ["general", "engineering", "incidents", "releases"] as const;
const STEP_DELAYS = {
firstPrompt: 0.06,
firstReply: 0.65,
followUp: 1.35,
finalReply: 2.05,
} as const;
const TYPING_VARIANTS: Variants = {
hidden: { opacity: 0 },
shown: {
opacity: [0, 1, 1, 0, 0, 1, 1, 0],
transition: {
duration: 2.4,
times: [0, 0.08, 0.24, 0.28, 0.56, 0.62, 0.84, 0.9],
ease: "linear",
},
},
};
const SLACK_COMPONENTS = {
mention: <SlackMention />,
host: (
<span className="rounded-[3px] border border-white/10 bg-[#222529] px-1.5 py-[1px] font-mono text-[11.5px] text-[#E8912D]" />
),
pr: <span className="font-medium text-[#1D9BD1] underline decoration-[#1D9BD1]/40" />,
};
export function SlackSourceMockup({ active, reduceMotion }: SourceMockupProps) {
const { t } = useTranslation();
return (
<MockupStageWindow
ariaLabel={t("hub.demo.slack.alt")}
active={active}
reduceMotion={reduceMotion}
className="border-[#35373B] bg-[#1A1D21]"
>
<SlackWindowChrome />
<div className="grid min-h-0 flex-1 grid-cols-1 md:grid-cols-[164px_minmax(0,1fr)]">
<SlackSidebar />
<div className="flex min-h-0 min-w-0 flex-col bg-[#1A1D21]">
<SlackChannelHeader />
<SlackMessageFeed />
<SlackComposer />
<SlackTypingStatus reduced={reduceMotion} />
</div>
</div>
</MockupStageWindow>
);
}
function SlackWindowChrome() {
const { t } = useTranslation();
return (
<div className="flex h-9 shrink-0 items-center justify-between border-b border-[#2C2D30] bg-[#121016] px-3.5">
<div className="flex items-center gap-3">
<WindowTrafficLights />
<div className="hidden items-center gap-1 text-[#ABABAD]/60 sm:flex" aria-hidden="true">
<ChevronLeft className="h-3.5 w-3.5" />
<ChevronRight className="h-3.5 w-3.5" />
</div>
</div>
<div className="flex h-6 w-44 items-center gap-1.5 rounded-[5px] bg-white/[0.08] px-2.5 text-[11px] text-[#ABABAD] sm:w-56">
<Search className="h-3 w-3 shrink-0 text-[#ABABAD]/75" aria-hidden="true" />
<span className="truncate">{t("hub.demo.slack.searchPlaceholder")}</span>
</div>
<SlackColorMark className="h-3.5 w-3.5 shrink-0" />
</div>
);
}
function SlackSidebar() {
const { t } = useTranslation();
return (
<aside
aria-hidden="true"
className="hidden flex-col border-r border-[#2C2D30] bg-[#19171D] md:flex"
>
<div className="flex items-center justify-between border-b border-white/[0.07] px-3 py-2.5">
<div className="flex items-center gap-1 text-[13.5px] font-bold text-[#F8F8F8]">
<span>Paseo</span>
<ChevronDown className="h-3.5 w-3.5 text-[#ABABAD]" />
</div>
<SquarePen className="h-3.5 w-3.5 text-[#ABABAD]" />
</div>
<div className="space-y-4 px-2 py-3 text-[12.5px]">
<div className="space-y-0.5">
<p className="px-2 pb-1 text-[11px] font-medium text-[#ABABAD]/75">
{t("hub.demo.slack.channels")}
</p>
{SIDEBAR_CHANNELS.map((channel) => (
<div
key={channel}
className={`flex items-center gap-1.5 rounded-[6px] px-2 py-1 ${
channel === "engineering" ? "bg-[#1164A3] font-medium text-white" : "text-[#ABABAD]"
}`}
>
<Hash className="h-3.5 w-3.5 shrink-0 opacity-80" />
<span className="truncate">{channel}</span>
</div>
))}
</div>
<div className="space-y-0.5">
<p className="px-2 pb-1 text-[11px] font-medium text-[#ABABAD]/75">
{t("hub.demo.slack.apps")}
</p>
<div className="flex items-center gap-2 rounded-[6px] px-2 py-1 text-[#D1D2D3]">
<span className="relative flex h-4 w-4 shrink-0 items-center justify-center rounded-[4px] bg-[#101615] ring-1 ring-white/15">
<PaseoMark className="h-2.5 w-2.5 text-white" />
<span className="absolute -right-0.5 -bottom-0.5 h-1.5 w-1.5 rounded-full bg-[#2BAC76] ring-1 ring-[#19171D]" />
</span>
<span className="truncate">paseo-bot</span>
</div>
</div>
</div>
</aside>
);
}
function SlackChannelHeader() {
const { t } = useTranslation();
return (
<div className="flex shrink-0 items-center justify-between gap-3 border-b border-[#2C2D30] px-4 py-2">
<div className="flex min-w-0 items-center gap-2">
<div className="flex items-center gap-1 text-[14px] font-bold text-[#F8F8F8]">
<Hash className="h-3.5 w-3.5 shrink-0 text-[#D1D2D3]" aria-hidden="true" />
<span>engineering</span>
</div>
<span className="hidden truncate text-[11.5px] text-[#ABABAD] sm:inline">
{t("hub.demo.slack.channelTopic")}
</span>
</div>
<div
aria-hidden="true"
className="flex shrink-0 items-center gap-1.5 rounded-[5px] border border-[#35373B] px-2 py-0.5 text-[11px] text-[#ABABAD]"
>
<div className="flex -space-x-1">
<MoAvatar size="xs" rounded="rounded-[3px]" className="ring-1 ring-[#1A1D21]" />
<span className="flex h-4 w-4 items-center justify-center rounded-[3px] bg-[#101615] ring-1 ring-[#1A1D21]">
<PaseoMark className="h-2.5 w-2.5 text-white" />
</span>
</div>
<span className="tabular-nums">4</span>
</div>
</div>
);
}
function SlackMessageFeed() {
const { t } = useTranslation();
return (
<div className="flex-1 space-y-2.5 px-4 py-2.5">
<MockupStep delay={STEP_DELAYS.firstPrompt}>
<SlackMessage author="mo" time="9:41 AM">
<p>
<Trans i18nKey="hub.demo.slack.showIssues" components={SLACK_COMPONENTS} />
</p>
</SlackMessage>
</MockupStep>
<div className="ml-2.5 sm:ml-3.5">
<MockupStep
delay={STEP_DELAYS.firstReply}
className="space-y-1.5 border-l-2 border-[#2C2D30] pb-2.5 pl-3 sm:pl-3.5"
>
<div className="flex items-center gap-2 text-[11px]">
<span className="font-medium text-[#1D9BD1]">{t("hub.demo.slack.threadReplies")}</span>
<span className="h-px flex-1 bg-[#2C2D30]" aria-hidden="true" />
</div>
<SlackMessage author="paseo-bot" time="9:41 AM" bot>
<p>{t("hub.demo.slack.issuesOpen")}</p>
<ul className="mt-1 space-y-0.5 border-l-[3px] border-[#36C5F0] pl-2.5 text-[12px]">
{DEMO_ISSUES.map((issue) => (
<li key={issue.id} className="flex flex-wrap items-baseline gap-x-1.5">
<span className="font-mono text-[11.5px] font-medium text-[#1D9BD1]">
{issue.id}
</span>
<span className="text-[#D1D2D3]">{issue.title}</span>
</li>
))}
</ul>
</SlackMessage>
</MockupStep>
<MockupStep
delay={STEP_DELAYS.followUp}
className="border-l-2 border-[#2C2D30] pb-2.5 pl-3 sm:pl-3.5"
>
<SlackMessage author="mo" time="9:43 AM">
<p>
<Trans i18nKey="hub.demo.slack.createPr" components={SLACK_COMPONENTS} />
</p>
</SlackMessage>
</MockupStep>
<MockupStep
delay={STEP_DELAYS.finalReply}
className="border-l-2 border-[#2C2D30] pl-3 sm:pl-3.5"
>
<SlackMessage author="paseo-bot" time="9:48 AM" bot>
<p>
<Trans i18nKey="hub.demo.slack.ranOn" components={SLACK_COMPONENTS} />
</p>
<SlackPrAttachment />
</SlackMessage>
</MockupStep>
</div>
</div>
);
}
function SlackPrAttachment() {
const { t } = useTranslation();
return (
<div className="mt-1.5 space-y-1.5 border-l-[3px] border-[#2BAC76] pl-2.5">
<div className="flex flex-wrap items-center gap-1.5">
<span className="inline-flex items-center gap-1 rounded-[4px] bg-[#2BAC76]/15 px-2 py-0.5 font-mono text-[11px] text-[#4CD99B]">
<GitPullRequest className="h-3 w-3" aria-hidden="true" />
{t("hub.demo.slack.filesChanged")}
</span>
<span className="inline-flex items-center gap-1 rounded-[4px] border border-[#35373B] bg-[#222529] px-2 py-0.5 font-mono text-[11px] text-[#ABABAD]">
<Check className="h-3 w-3 text-[#2BAC76]" aria-hidden="true" />
{t("hub.demo.shared.testsPassed")}
</span>
</div>
<div>
<OpenInPaseoChip variant="slack" />
</div>
</div>
);
}
function SlackMessage({
author,
time,
bot,
children,
}: {
author: string;
time: string;
bot?: boolean;
children: ReactNode;
}) {
const { t } = useTranslation();
return (
<div className="flex items-start gap-2.5">
{bot ? (
<PaseoBotAvatar size="sm" className="mt-0.5 h-8 w-8" />
) : (
<MoAvatar size="sm" className="mt-0.5 h-8 w-8" />
)}
<div className="min-w-0 flex-1 space-y-0.5">
<div className="flex flex-wrap items-center gap-1.5">
<span className="text-[13px] font-bold text-[#F8F8F8]">{author}</span>
{bot ? (
<span className="rounded-[3px] bg-[#2C2D30] px-1.5 py-[1px] text-[9.5px] font-semibold uppercase tracking-wide text-[#ABABAD]">
{t("hub.demo.shared.appBadge")}
</span>
) : null}
<span className="text-[10.5px] text-[#ABABAD]">{time}</span>
</div>
<div className="text-[12.5px] leading-[1.42] text-[#D1D2D3]">{children}</div>
</div>
</div>
);
}
function SlackMention() {
return (
<span className="rounded-[3px] bg-[#1D9BD1]/20 px-1 py-[1px] font-medium text-[#1D9BD1]">
@paseo-bot
</span>
);
}
function SlackComposer() {
const { t } = useTranslation();
return (
<div
aria-hidden="true"
className="mx-4 mt-auto rounded-[8px] border border-[#35373B] bg-[#222529]"
>
<div className="px-3 py-1.5 text-[12.5px] text-[#ABABAD]/70">
{t("hub.demo.slack.composerPlaceholder")}
</div>
<div className="flex items-center justify-between border-t border-white/[0.06] px-2.5 py-1">
<div className="flex items-center gap-2.5 text-[#ABABAD]/60">
<Plus className="h-3.5 w-3.5" />
<AtSign className="h-3.5 w-3.5" />
<Code className="h-3.5 w-3.5" />
</div>
<span className="inline-flex h-5 w-6 items-center justify-center rounded-[4px] bg-[#007A5A]/80 text-white">
<SendHorizontal className="h-3 w-3" />
</span>
</div>
</div>
);
}
function SlackTypingStatus({ reduced }: { reduced: boolean }) {
const { t } = useTranslation();
return (
<div aria-hidden="true" className="flex h-6 shrink-0 items-center px-4 pb-1">
{reduced ? null : (
<motion.span
variants={TYPING_VARIANTS}
className="inline-flex items-center gap-1.5 text-[11px] text-[#ABABAD]"
>
<span className="h-1.5 w-1.5 animate-pulse rounded-full bg-[#2BAC76]" />
{t("hub.demo.slack.typing")}
</motion.span>
)}
</div>
);
}
export function SlackColorMark(props: React.SVGProps<SVGSVGElement>) {
return (
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" aria-hidden="true" {...props}>
<path
fill="#E01E5A"
d="M5.042 15.165a2.528 2.528 0 0 1-2.52 2.523A2.528 2.528 0 0 1 0 15.165a2.527 2.527 0 0 1 2.522-2.52h2.52v2.52zM6.313 15.165a2.527 2.527 0 0 1 2.521-2.52 2.527 2.527 0 0 1 2.521 2.52v6.313A2.528 2.528 0 0 1 8.834 24a2.528 2.528 0 0 1-2.521-2.522v-6.313z"
/>
<path
fill="#36C5F0"
d="M8.834 5.042a2.528 2.528 0 0 1-2.521-2.52A2.528 2.528 0 0 1 8.834 0a2.528 2.528 0 0 1 2.521 2.522v2.52H8.834zM8.834 6.313a2.528 2.528 0 0 1 2.521 2.521 2.528 2.528 0 0 1-2.521 2.521H2.522A2.528 2.528 0 0 1 0 8.834a2.528 2.528 0 0 1 2.522-2.521h6.312z"
/>
<path
fill="#2EB67D"
d="M18.956 8.834a2.528 2.528 0 0 1 2.522-2.521A2.528 2.528 0 0 1 24 8.834a2.528 2.528 0 0 1-2.522 2.521h-2.522V8.834zM17.688 8.834a2.528 2.528 0 0 1-2.523 2.521 2.527 2.527 0 0 1-2.52-2.521V2.522A2.527 2.527 0 0 1 15.165 0a2.528 2.528 0 0 1 2.523 2.522v6.312z"
/>
<path
fill="#ECB22E"
d="M15.165 18.956a2.528 2.528 0 0 1 2.523 2.522A2.528 2.528 0 0 1 15.165 24a2.527 2.527 0 0 1-2.52-2.522v-2.522h2.52zM15.165 17.688a2.527 2.527 0 0 1-2.52-2.523 2.526 2.526 0 0 1 2.52-2.52h6.313A2.527 2.527 0 0 1 24 15.165a2.528 2.528 0 0 1-2.522 2.523h-6.313z"
/>
</svg>
);
}
@@ -0,0 +1,189 @@
import { ArrowDown, Check, Terminal, Webhook } from "lucide-react";
import { Trans, useTranslation } from "react-i18next";
import {
MockupStageWindow,
MockupStep,
OpenInPaseoChip,
PaseoBotAvatar,
type SourceMockupProps,
WindowTrafficLights,
} from "./shared";
const STEP_DELAYS = {
curl: 0.06,
response: 0.65,
runCard: 1.25,
} as const;
const WEBHOOK_ID = "wh_4PCfLx4q46HniZpIeiThI4BmNC4zHGFY";
const RUN_ID = "0197e5d2-a70c-4ad0-b7aa-a29154a6bc72";
const ACCEPTED_RESPONSE = JSON.stringify({ status: "accepted", runId: RUN_ID });
const WEBHOOK_COMPONENTS = {
code: <code className="font-mono text-[11px] text-white/90" />,
pr: <span className="font-mono text-[#6CB17B]">#2834</span>,
};
export function WebhooksSourceMockup({ active, reduceMotion }: SourceMockupProps) {
const { t } = useTranslation();
return (
<MockupStageWindow
ariaLabel={t("hub.demo.webhooks.alt")}
active={active}
reduceMotion={reduceMotion}
className="border-white/[0.1] bg-[#0C1110]"
>
<WebhookTerminalChrome />
<div className="flex flex-1 flex-col justify-between gap-2.5 p-4">
<div className="space-y-3">
<WebhookCurlBlock />
<WebhookResponseBlock />
</div>
<WebhookRouteConnector />
<WebhookRunCard />
</div>
</MockupStageWindow>
);
}
function WebhookTerminalChrome() {
return (
<div className="flex h-9 shrink-0 items-center justify-between gap-2 border-b border-white/[0.08] bg-[#131918] px-3.5">
<div className="flex min-w-0 items-center gap-3">
<WindowTrafficLights />
<span className="inline-flex min-w-0 items-center gap-1.5 truncate font-mono text-[11.5px] text-white/65">
<Terminal className="h-3.5 w-3.5 shrink-0 text-white/45" aria-hidden="true" />
<span className="truncate">mo@devbox — zsh</span>
</span>
</div>
<span className="hidden shrink-0 items-center gap-1.5 rounded border border-white/10 bg-white/[0.04] px-2 py-0.5 font-mono text-[10.5px] text-accent-text sm:inline-flex">
<Webhook className="h-3 w-3" aria-hidden="true" />
POST /webhooks/{WEBHOOK_ID}
</span>
</div>
);
}
function WebhookRouteConnector() {
const { t } = useTranslation();
return (
<MockupStep delay={0.95} className="flex items-center gap-2.5 px-1 text-[11px] text-white/45">
<span className="h-px flex-1 bg-white/[0.07]" aria-hidden="true" />
<span className="inline-flex items-center gap-1.5 font-mono text-accent-text/90">
<ArrowDown className="h-3 w-3" aria-hidden="true" />
{t("hub.demo.webhooks.routedLine")}
</span>
<span className="h-px flex-1 bg-white/[0.07]" aria-hidden="true" />
</MockupStep>
);
}
function WebhookCurlBlock() {
return (
<MockupStep delay={STEP_DELAYS.curl}>
<pre className="font-mono text-[11.5px] leading-[1.6] wrap-anywhere whitespace-pre-wrap text-white/80">
<code>
<span className="select-none text-accent-text">$ </span>
<span className="text-white">curl</span> <span className="text-sky-300/90">-X POST</span>{" "}
<span className="text-emerald-300/90">
https://hub.paseo.sh/webhooks/
<wbr />
{WEBHOOK_ID}
</span>{" "}
<span className="text-white/35">\</span>
{"\n"}
{" "}
<span className="text-sky-300/90">-H</span>{" "}
<span className="text-amber-200/85">
&quot;Authorization: Bearer $WEBHOOK_TOKEN&quot;
</span>{" "}
<span className="text-white/35">\</span>
{"\n"}
{" "}
<span className="text-sky-300/90">-H</span>{" "}
<span className="text-amber-200/85">&quot;Content-Type: application/json&quot;</span>{" "}
<span className="text-white/35">\</span>
{"\n"}
{" "}
<span className="text-sky-300/90">-d</span>{" "}
<span className="text-white/75">
&#39;&#123;&quot;error&quot;:&quot;ECONNRESET&quot;&#125;&#39;
</span>
</code>
</pre>
</MockupStep>
);
}
function WebhookResponseBlock() {
return (
<MockupStep
delay={STEP_DELAYS.response}
className="rounded-lg border border-brand-green/35 bg-brand-green/[0.08] px-3 py-2 font-mono text-[11.5px] leading-[1.55]"
>
<div className="flex items-center gap-2 text-[#6CB17B]">
<span className="font-semibold">HTTP/2 202 Accepted</span>
<span className="text-white/35">·</span>
<span className="text-white/55">42ms</span>
</div>
<div className="mt-0.5 wrap-anywhere text-white/80">{ACCEPTED_RESPONSE}</div>
</MockupStep>
);
}
function WebhookRunCard() {
const { t } = useTranslation();
return (
<MockupStep
delay={STEP_DELAYS.runCard}
className="rounded-lg border border-white/[0.09] bg-[#141B19] p-3.5"
>
<div className="flex flex-wrap items-center justify-between gap-2 border-b border-white/[0.07] pb-2.5">
<div className="flex items-center gap-2">
<PaseoBotAvatar size="sm" />
<div>
<div className="flex items-center gap-1.5 text-[12.5px]">
<span className="font-semibold text-white/95">paseo-bot</span>
<span className="font-mono text-[11px] text-white/45">{RUN_ID.slice(0, 8)}…</span>
</div>
<p className="text-[11px] text-white/55">{t("hub.demo.webhooks.runMeta")}</p>
</div>
</div>
<span className="inline-flex items-center gap-1.5 rounded-full border border-brand-green/50 bg-brand-green/20 px-2 py-0.5 text-[10.5px] font-medium text-accent-text">
<span className="h-1.5 w-1.5 rounded-full bg-[#35C264]" />
{t("hub.demo.webhooks.statusDone")}
</span>
</div>
<ul className="mt-2.5 space-y-1.5 text-[12px] text-white/75">
<li className="flex items-start gap-2">
<Check className="mt-0.5 h-3.5 w-3.5 shrink-0 text-accent-text" aria-hidden="true" />
<span>
<Trans i18nKey="hub.demo.webhooks.trace1" components={WEBHOOK_COMPONENTS} />
</span>
</li>
<li className="flex items-start gap-2">
<Check className="mt-0.5 h-3.5 w-3.5 shrink-0 text-accent-text" aria-hidden="true" />
<span>
<Trans i18nKey="hub.demo.webhooks.trace2" components={WEBHOOK_COMPONENTS} />
</span>
</li>
<li className="flex items-start gap-2">
<Check className="mt-0.5 h-3.5 w-3.5 shrink-0 text-accent-text" aria-hidden="true" />
<span>
<Trans i18nKey="hub.demo.webhooks.trace3" components={WEBHOOK_COMPONENTS} />
</span>
</li>
</ul>
<div className="mt-3 flex flex-wrap items-center justify-between gap-2 border-t border-white/[0.07] pt-2.5">
<OpenInPaseoChip variant="brand" />
<span className="font-mono text-[11px] text-white/45">
{t("hub.demo.webhooks.triggeredBy")}
</span>
</div>
</MockupStep>
);
}
@@ -0,0 +1,245 @@
import { ArrowDown, ArrowRight, Clock, Webhook } from "lucide-react";
import type * as React from "react";
import { useTranslation } from "react-i18next";
import { ClaudeCodeIcon, CodexIcon, OpenCodeIcon } from "~/components/agent-icons";
import { DiscordIcon, GitHubIcon, LinearIcon, SlackIcon } from "~/components/brand-icons";
import { HubLockup, PaseoMark } from "~/components/paseo-brand";
export type HubTriggerSourceId =
| "github"
| "linear"
| "slack"
| "discord"
| "schedules"
| "webhooks";
export interface HubTriggerSource {
id: HubTriggerSourceId;
Icon: React.ComponentType<{ className?: string }>;
}
/** The six automation sources Hub accepts, shared by the homepage and /hub. */
export const HUB_TRIGGER_SOURCES: readonly HubTriggerSource[] = [
{ id: "github", Icon: GitHubIcon },
{ id: "linear", Icon: LinearIcon },
{ id: "slack", Icon: SlackIcon },
{ id: "discord", Icon: DiscordIcon },
{ id: "schedules", Icon: Clock },
{ id: "webhooks", Icon: Webhook },
] as const;
/** Examples of agent harnesses on connected daemons. */
export const HUB_AGENT_HARNESSES = [
{ name: "Claude Code", Icon: ClaudeCodeIcon },
{ name: "Codex", Icon: CodexIcon },
{ name: "OpenCode", Icon: OpenCodeIcon },
] as const;
const DIAGRAM_DAEMONS = [
{ name: "MacBook Pro", agents: HUB_AGENT_HARNESSES },
{ name: "Hetzner VM", agents: HUB_AGENT_HARNESSES },
] as const;
const DIAGRAM_CLIENTS = ["desktop", "web", "mobile", "cli"] as const;
/** Compact flow diagram for the homepage Paseo Hub section, sitting directly on the page background. */
export function HubLandingFlow() {
const { t } = useTranslation();
return (
<div className="grid items-center gap-5 lg:grid-cols-[minmax(0,1fr)_auto_minmax(0,12rem)_auto_minmax(0,1fr)]">
<div className="space-y-2.5">
<p className="text-[11px] uppercase tracking-wide text-white/35">
{t("landing.hubSection.flowTriggers")}
</p>
<div className="grid grid-cols-2 gap-2">
{HUB_TRIGGER_SOURCES.map(({ id, Icon }) => (
<div
key={id}
className="flex items-center gap-2 rounded-lg border border-white/10 bg-white/[0.03] px-3 py-2"
>
<Icon className="h-3.5 w-3.5 shrink-0 text-white/70" />
<span className="truncate text-xs font-medium text-white/85">
{t(`hub.sources.${id}.name`)}
</span>
</div>
))}
</div>
</div>
<FlowArrow />
<div className="rounded-xl border border-brand-green/50 bg-brand-green/[0.12] px-5 py-5 text-center">
<p className="flex justify-center">
<HubLockup className="h-5 w-auto text-foreground" />
<span className="sr-only">{t("hub.shape.hub")}</span>
</p>
<p className="mt-2 text-xs text-white/70">{t("hub.shape.hubHosting")}</p>
</div>
<FlowArrow />
<div className="space-y-2.5">
<p className="text-[11px] uppercase tracking-wide text-white/35">
{t("landing.hubSection.flowDaemons")}
</p>
<div className="space-y-2">
{DIAGRAM_DAEMONS.map((daemon) => (
<CompactDaemonRow key={daemon.name} name={daemon.name} agents={daemon.agents} />
))}
<div className="flex items-center gap-2 rounded-lg border border-dashed border-white/10 bg-white/[0.015] px-3 py-2 text-xs text-white/60">
<PaseoMark className="h-3.5 w-3.5 shrink-0 text-white/75" />
<span className="truncate">{t("landing.hubSection.flowOpenSession")}</span>
</div>
</div>
</div>
</div>
);
}
function CompactDaemonRow({
name,
agents,
}: {
name: string;
agents: readonly { name: string; Icon: React.ComponentType<{ className?: string }> }[];
}) {
return (
<div className="flex items-center justify-between gap-2 rounded-lg border border-white/10 bg-white/[0.03] px-3 py-2">
<span className="flex min-w-0 items-center gap-2">
<MachineIcon className="h-4 w-4 shrink-0 text-white/60" />
<span className="truncate text-xs font-medium text-white/85">{name}</span>
</span>
<span className="flex shrink-0 items-center gap-1.5 text-white/45">
{agents.map(({ name: agentName, Icon }) => (
<span key={agentName} title={agentName}>
<Icon className="h-3.5 w-3.5" />
</span>
))}
</span>
</div>
);
}
/** Full vertical infrastructure diagram for the /hub page. */
export function HubArchitectureDiagram() {
const { t } = useTranslation();
return (
<div className="rounded-xl border border-white/[0.08] bg-white/[0.015] p-6 md:p-8">
<div className="flex flex-col items-center">
<DiagramRow label={t("hub.shape.triggersRow")}>
{HUB_TRIGGER_SOURCES.map(({ id, Icon }) => (
<DiagramCard key={id} Icon={Icon} name={t(`hub.sources.${id}.name`)} />
))}
</DiagramRow>
<Connector label={t("hub.shape.webhooks")} />
<div className="w-full max-w-xs rounded-xl border border-brand-green/50 bg-brand-green/[0.12] px-6 py-5 text-center">
<p className="flex justify-center">
<HubLockup className="h-[22px] w-auto text-foreground" />
<span className="sr-only">{t("hub.shape.hub")}</span>
</p>
<p className="mt-1.5 text-xs text-white/70">{t("hub.shape.hubHosting")}</p>
</div>
<Connector label={t("hub.shape.sameRpcs")} />
<DiagramRow label={t("hub.shape.daemonsRow")}>
{DIAGRAM_DAEMONS.map((daemon) => (
<div
key={daemon.name}
className="flex items-center gap-3 rounded-xl border border-white/10 bg-white/[0.03] px-4 py-3"
>
<span className="text-white/70">
<MachineIcon className="h-5 w-5" />
</span>
<span className="text-sm font-medium">{daemon.name}</span>
<span className="flex items-center gap-2 border-l border-white/10 pl-3 text-white/45">
{daemon.agents.map(({ name, Icon }) => (
<span key={name} title={name}>
<Icon className="h-4 w-4" />
</span>
))}
</span>
</div>
))}
</DiagramRow>
<Connector label={t("hub.shape.directOrRelay")} />
<DiagramRow label={t("hub.shape.appsRow")}>
{DIAGRAM_CLIENTS.map((client) => (
<DiagramCard key={client} name={t(`hub.shape.${client}`)} />
))}
</DiagramRow>
</div>
</div>
);
}
function FlowArrow() {
return (
<div className="flex items-center justify-center text-white/30" aria-hidden="true">
<ArrowRight className="hidden h-4 w-4 lg:block" />
<ArrowDown className="h-4 w-4 lg:hidden" />
</div>
);
}
function DiagramRow({ label, children }: { label: string; children: React.ReactNode }) {
return (
<div className="w-full space-y-2.5">
<p className="text-center text-xs uppercase tracking-wide text-white/30">{label}</p>
<div className="flex flex-wrap justify-center gap-2.5">{children}</div>
</div>
);
}
function DiagramCard({
name,
Icon,
}: {
name: string;
Icon?: React.ComponentType<{ className?: string }>;
}) {
return (
<div className="flex items-center gap-2 rounded-xl border border-white/10 bg-white/[0.03] px-3.5 py-2.5">
{Icon ? (
<span className="text-white/70">
<Icon className="h-4 w-4" />
</span>
) : null}
<span className="text-sm font-medium">{name}</span>
</div>
);
}
function Connector({ label }: { label: string }) {
return (
<div className="flex flex-col items-center gap-2 py-4">
<div className="h-5 w-px border-l border-dashed border-white/25" />
<p className="text-center text-[11px] text-white/35">{label}</p>
<div className="h-5 w-px border-l border-dashed border-white/25" />
</div>
);
}
function MachineIcon({ className }: { className?: string }) {
return (
<svg
viewBox="0 0 24 24"
fill="none"
stroke="currentColor"
strokeWidth="1.5"
strokeLinecap="round"
strokeLinejoin="round"
aria-hidden="true"
className={className}
>
<rect x="2" y="2" width="20" height="8" rx="2" />
<rect x="2" y="14" width="20" height="8" rx="2" />
<circle cx="6" cy="6" r="1" />
<circle cx="6" cy="18" r="1" />
</svg>
);
}
+320 -200
View File
@@ -88,8 +88,15 @@ import {
OpenCodeIcon,
PiIcon,
} from "~/components/agent-icons";
import { DiscordIcon, GitHubIcon, SlackIcon } from "~/components/brand-icons";
import { PaseoHubMark } from "~/components/paseo-brand";
import { HubLandingFlow } from "~/components/hub-flow";
import {
ChapterBand,
ChapterDivider,
HairlineGrid,
PageHeaderBand,
SectionOpener,
} from "~/components/page-frame";
import { PaseoHubLockup, PaseoHubMark, PaseoMark } from "~/components/paseo-brand";
import {
MobileChat,
MobileDiff,
@@ -100,78 +107,146 @@ import {
} from "~/components/mockup";
import { FAQItem } from "~/components/faq-item";
import { SiteFooter } from "~/components/site-footer";
import { SponsorSection, SponsorsSection } from "~/components/sponsorship";
import { SiteHeader } from "~/components/site-header";
import { HomepageSponsorsSection } from "~/components/sponsorship";
import "~/styles.css";
interface LandingPageProps {
title: React.ReactNode;
subtitle: React.ReactNode;
pluginCount?: number | null;
showHubEyebrow?: boolean;
}
export function LandingPage({ title, subtitle }: LandingPageProps) {
export function LandingPage({
title,
subtitle,
pluginCount = null,
showHubEyebrow = false,
}: LandingPageProps) {
return (
<CursorFieldProvider>
{/* Hero section with background image */}
<div className="relative bg-cover bg-center bg-no-repeat">
<div className="relative px-6 pt-4 pb-10 md:px-32 md:pt-6 md:pb-12 max-w-7xl mx-auto">
<Nav />
<Hero title={title} subtitle={subtitle} />
<GetStarted />
</div>
<div className="min-h-screen bg-background">
<PageHeaderBand />
{/* Mockup - inside hero so it's above the gradient, positioned to overflow into black section */}
<motion.div
initial={FADE_IN_UP_40}
animate={FADE_IN}
transition={EASE_OUT_08_DELAY_05}
className="relative px-6 md:px-8 pt-4 md:pt-8 pb-8 md:pb-16"
>
<div className="max-w-7xl mx-auto">
<HeroMockup />
</div>
</motion.div>
</div>
<main>
{/* Opening bookend: centered hero, interactive desktop mockup, and phone trio */}
<ChapterBand spacing="none" ruled={false} ticks={false} framed={false}>
<div className="pt-12 pb-8 md:pt-16 md:pb-10">
<Hero title={title} subtitle={subtitle} showHubEyebrow={showHubEyebrow} />
<GetStarted />
</div>
{/* Phone showcase */}
<PhoneShowcase />
<motion.div
initial={FADE_IN_UP_40}
animate={FADE_IN}
transition={EASE_OUT_08_DELAY_05}
className="relative pt-4 pb-10 md:pt-6 md:pb-14"
>
<div>
<HeroMockup />
</div>
</motion.div>
{/* Content section */}
<div className="landing-content bg-background">
<main className="p-6 md:p-20 md:pt-40 max-w-5xl mx-auto">
<div className="space-y-24">
<PhoneShowcase />
</ChapterBand>
{/* Chapter 1: Community proof */}
<ChapterBand spacing="compact">
<SocialProofWall />
<MultiProviderSection />
<TurnkeySection />
<ExtensibleSection />
<AutomationSection />
<SponsorsSection placement="page" />
<SponsorSection />
<PhilosophySection />
</ChapterBand>
{/* Chapter 2: The product (Providers, Deployment, Extensibility, Automation) */}
<ChapterBand spacing="none">
<div className="py-16 md:py-20">
<MultiProviderSection />
</div>
<ChapterDivider />
<div className="py-16 md:py-20">
<TurnkeySection />
</div>
<ChapterDivider />
<div className="py-16 md:py-20">
<ExtensibleSection pluginCount={pluginCount} />
</div>
<ChapterDivider />
<div className="py-16 md:py-20">
<AutomationSection />
</div>
</ChapterBand>
{/* Chapter 3: Paseo Hub */}
<ChapterBand spacing="chapter" tint="subtle">
<HubSection />
</ChapterBand>
{/* Chapter 4: Open source philosophy and consolidated sponsorship */}
<ChapterBand spacing="none">
<div className="py-16 md:py-20">
<PhilosophySection />
</div>
<ChapterDivider />
<div className="py-16 md:py-20">
<HomepageSponsorsSection />
</div>
</ChapterBand>
{/* Chapter 5: FAQ */}
<ChapterBand spacing="section">
<FAQ />
</div>
</ChapterBand>
{/* Closing bookend: centered download CTA */}
<ChapterBand spacing="chapter" tint="subtle">
<ClosingCtaSection />
</ChapterBand>
</main>
<SiteFooter sponsors={false} />
<SiteFooter width="default" sponsors={false} />
</div>
</CursorFieldProvider>
);
}
function Nav() {
function Hero({
title,
subtitle,
showHubEyebrow = false,
}: {
title: React.ReactNode;
subtitle: React.ReactNode;
showHubEyebrow?: boolean;
}) {
return (
<nav className="mb-20 md:mb-24">
<SiteHeader />
</nav>
<div className="space-y-6 text-center">
{showHubEyebrow ? <HubHeroEyebrow /> : null}
<h1 className="font-display text-4xl font-semibold tracking-[-0.025em] leading-[1.02] md:text-6xl">
{title}
</h1>
<p className="mx-auto max-w-lg text-base leading-relaxed text-white/70 md:text-lg">
{subtitle}
</p>
</div>
);
}
function Hero({ title, subtitle }: { title: React.ReactNode; subtitle: React.ReactNode }) {
function HubHeroEyebrow() {
const { t } = useTranslation();
const localize = useLocalizePath();
return (
<div className="space-y-6 text-center">
<h1 className="text-4xl md:text-6xl font-medium tracking-tight leading-[0.95]">{title}</h1>
<p className="text-base leading-relaxed text-white/70 md:text-lg max-w-lg mx-auto">
{subtitle}
</p>
<div className="flex justify-center">
<a
href={localize("/hub")}
className="group inline-flex max-w-full items-center gap-2 whitespace-nowrap rounded-full border border-white/10 bg-white/[0.04] px-3 py-1 text-xs text-white/75 transition-colors hover:border-white/20 hover:bg-white/[0.08] hover:text-white"
>
<PaseoHubMark className="h-3.5 w-3.5 shrink-0 text-white/90" />
<span className="font-medium text-white/90">{t("landing.hubEyebrow.product")}</span>
<span aria-hidden="true" className="h-3 w-px shrink-0 bg-white/15" />
<span className="truncate text-white/65">{t("landing.hubEyebrow.label")}</span>
<ArrowRight
aria-hidden="true"
className="h-3.5 w-3.5 shrink-0 text-white/45 transition-transform group-hover:translate-x-0.5 group-hover:text-white/80"
/>
</a>
</div>
);
}
@@ -301,12 +376,14 @@ function AgentBadge({ name, Icon }: (typeof FEATURED_AGENTS)[number]) {
}
function FeatureSection({
eyebrow,
title,
description,
badge,
links,
children,
}: {
eyebrow?: string;
title: string;
description: string;
badge?: string;
@@ -320,54 +397,18 @@ function FeatureSection({
viewport={VIEWPORT_60}
transition={EASE_OUT_05}
>
<SectionTitle title={title} description={description} badge={badge} links={links} />
<SectionOpener
eyebrow={eyebrow}
title={title}
description={description}
badge={badge}
links={links}
/>
{children}
</motion.section>
);
}
function SectionTitle({
title,
description,
badge,
links,
}: {
title: string;
description: string;
badge?: string;
links?: ReadonlyArray<{ href: string; label: string }>;
}) {
return (
<div className="mb-12 space-y-2">
<div className="flex items-center gap-3">
<h2 className="text-3xl font-medium">{title}</h2>
{badge && (
<span className="rounded-full bg-emerald-400/10 px-2 py-1 text-xs text-emerald-300">
{badge}
</span>
)}
</div>
<p className="text-base text-pretty text-muted-foreground max-w-lg">{description}</p>
{links ? (
<div className="flex flex-wrap gap-x-4 gap-y-1 pt-1 text-xs">
{links.map((link) => (
<a
key={link.href}
href={link.href}
target="_blank"
rel="noopener noreferrer"
className="inline-flex items-center gap-1 text-extra-muted-foreground transition-colors hover:text-muted-foreground"
>
{link.label}
<ExternalLink className="h-3 w-3" />
</a>
))}
</div>
) : null}
</div>
);
}
function SocialProofWall() {
const { t } = useTranslation();
return (
@@ -377,7 +418,7 @@ function SocialProofWall() {
viewport={VIEWPORT_60}
transition={EASE_OUT_05}
>
<SectionTitle
<SectionOpener
title={t("landing.socialProof.title")}
description={t("landing.socialProof.description")}
/>
@@ -424,7 +465,7 @@ function SocialProofCard({ tweet, inert }: { tweet: SocialProofTweet; inert?: bo
target="_blank"
rel="noreferrer"
tabIndex={inert ? -1 : undefined}
className="group flex h-[154px] w-[320px] shrink-0 flex-col justify-between overflow-hidden rounded-2xl border border-white/10 bg-white/[0.03] p-4 transition-colors hover:border-white/20 hover:bg-white/[0.05] md:w-[420px]"
className="group flex h-[154px] w-[300px] shrink-0 flex-col justify-between overflow-hidden rounded-xl border border-white/[0.08] bg-white/[0.02] p-4 transition-colors hover:border-white/20 hover:bg-white/[0.04] md:w-[380px]"
aria-label={t("landing.socialProof.readPost", { name: tweet.name })}
>
<div>
@@ -453,30 +494,34 @@ function MultiProviderSection() {
const localize = useLocalizePath();
return (
<FeatureSection
eyebrow={t("landing.eyebrows.providers")}
title={t("landing.providers.title")}
description={t("landing.providers.description")}
>
<div className="grid grid-cols-2 gap-2 sm:grid-cols-3 sm:gap-4">
<HairlineGrid columns="2-3">
{FEATURED_AGENTS.map((agent) => (
<div
key={agent.name}
className="flex items-center justify-center gap-2 rounded-xl border border-white/10 bg-white/[0.03] px-3 py-3 sm:gap-3 sm:px-5 sm:py-4"
className="flex items-center gap-3 bg-background px-5 py-4 transition-colors hover:bg-white/[0.025] sm:px-6 sm:py-5"
>
<span className="shrink-0 text-white/80">
<agent.Icon className="h-5 w-5 sm:h-7 sm:w-7" />
<agent.Icon className="h-5 w-5 sm:h-6 sm:w-6" />
</span>
<span className="truncate text-sm font-medium text-white/90 sm:text-base">
{agent.name}
</span>
<span className="truncate text-sm font-medium sm:text-base">{agent.name}</span>
</div>
))}
<a
href={localize("/agents")}
className="flex items-center justify-center gap-2 rounded-xl border border-dashed border-white/10 bg-white/[0.01] px-3 py-3 text-white/50 hover:text-white/80 hover:border-white/20 hover:bg-white/[0.03] transition-colors sm:gap-3 sm:px-5 sm:py-4"
className="flex items-center justify-between gap-2 bg-background px-5 py-4 text-white/55 transition-colors hover:bg-white/[0.025] hover:text-accent-text sm:px-6 sm:py-5"
>
<span className="text-sm font-medium sm:text-base">
{t("common.more", { count: ADDITIONAL_AGENT_COUNT })}
</span>
<ArrowRight className="h-4 w-4 shrink-0" aria-hidden="true" />
</a>
</div>
</HairlineGrid>
</FeatureSection>
);
}
@@ -489,13 +534,15 @@ function TurnkeySection() {
title={t("landing.runAnywhere.title")}
description={t("landing.runAnywhere.description")}
>
<div className="space-y-8">
<ProductLead
icon={Monitor}
title={t("landing.runAnywhere.desktopTitle")}
description={t("landing.runAnywhere.desktopDescription")}
/>
<div className="grid gap-4 md:grid-cols-3">
<div className="overflow-hidden rounded-xl border border-white/[0.08] bg-white/[0.08]">
<div className="bg-background p-6 md:p-7">
<ProductLead
icon={Monitor}
title={t("landing.runAnywhere.desktopTitle")}
description={t("landing.runAnywhere.desktopDescription")}
/>
</div>
<div className="grid gap-px border-t border-white/[0.08] md:grid-cols-3">
<TurnkeyExtensionCard
icon={Smartphone}
title={t("landing.runAnywhere.mobileTitle")}
@@ -517,7 +564,6 @@ function TurnkeySection() {
ctaHref={localize("/hub")}
ctaLabel={t("landing.runAnywhere.teamsCta")}
ctaIcon={PASEO_HUB_CTA_ICON}
showIntegrationIcons
/>
</div>
</div>
@@ -534,7 +580,6 @@ function TurnkeyExtensionCard({
ctaHref,
ctaLabel,
ctaIcon,
showIntegrationIcons = false,
}: {
icon: LucideIcon;
title: string;
@@ -542,34 +587,22 @@ function TurnkeyExtensionCard({
ctaHref: string;
ctaLabel: string;
ctaIcon?: React.ReactNode;
showIntegrationIcons?: boolean;
}) {
return (
<FeatureCard icon={Icon} title={title} description={description}>
<div className="flex items-center justify-between">
<a
href={ctaHref}
className="inline-flex items-center gap-1.5 rounded-full bg-foreground px-2.5 py-1.5 text-xs text-background transition-colors hover:bg-foreground/90"
>
{ctaIcon}
{ctaLabel}
<ArrowRight className="h-3.5 w-3.5" />
</a>
{showIntegrationIcons ? INTEGRATION_ICONS : null}
</div>
</FeatureCard>
<FeatureCell icon={Icon} title={title} description={description}>
<a
href={ctaHref}
className="inline-flex items-center gap-1.5 rounded-full bg-foreground px-3 py-1.5 text-xs font-medium text-background transition-colors hover:bg-foreground/90"
>
{ctaIcon}
{ctaLabel}
<ArrowRight className="h-3.5 w-3.5" />
</a>
</FeatureCell>
);
}
const INTEGRATION_ICONS = (
<span className="flex items-center gap-2 text-extra-muted-foreground">
<GitHubIcon className="h-4 w-4" />
<SlackIcon className="h-4 w-4" />
<DiscordIcon className="h-4 w-4" />
</span>
);
/** The lead product of a section: an icon tile and title on the page background. */
/** The lead product of a section: an icon tile and title. */
function ProductLead({
icon: Icon,
title,
@@ -584,13 +617,13 @@ function ProductLead({
return (
<div className="flex flex-col gap-6 sm:flex-row sm:items-center sm:justify-between">
<div className="flex items-center gap-4">
<div className="rounded-xl border border-white/10 bg-white/[0.06] p-3 text-muted-foreground">
<Icon className="h-6 w-6" strokeWidth={1.5} />
<div className="rounded-lg border border-white/[0.08] bg-white/[0.04] p-3 text-accent-text">
<Icon className="h-5 w-5" strokeWidth={1.5} />
</div>
<div className="space-y-0.5">
<h3 className="text-xl font-medium text-white/90">{title}</h3>
<h3 className="text-lg font-medium text-white/95">{title}</h3>
{description ? (
<p className="text-sm leading-relaxed text-white/50">{description}</p>
<p className="text-sm leading-relaxed text-white/55">{description}</p>
) : null}
</div>
</div>
@@ -599,8 +632,8 @@ function ProductLead({
);
}
/** A small card: icon and title on one line, the blurb below, an optional action last. */
function FeatureCard({
/** A hairline grid cell: icon and title on one line, the blurb below, an optional action last. */
function FeatureCell({
icon: Icon,
title,
description,
@@ -612,12 +645,12 @@ function FeatureCard({
children?: React.ReactNode;
}) {
return (
<div className="flex flex-col rounded-xl border border-white/10 bg-white/[0.025] p-5">
<div className="flex items-center gap-3">
<Icon className="h-5 w-5 shrink-0 text-extra-muted-foreground" strokeWidth={1.5} />
<h3 className="font-medium text-white/85">{title}</h3>
<div className="flex flex-col bg-background p-6">
<div className="flex items-center gap-2.5">
<Icon className="h-4 w-4 shrink-0 text-accent-text" strokeWidth={1.5} />
<h3 className="text-sm font-medium text-white/90">{title}</h3>
</div>
<p className="mt-3 text-sm leading-relaxed text-white/45">{description}</p>
<p className="mt-2.5 text-sm leading-relaxed text-white/55">{description}</p>
{children ? <div className="mt-auto pt-5">{children}</div> : null}
</div>
);
@@ -654,8 +687,11 @@ function AutomationSection() {
description={t("landing.automation.description")}
links={links}
>
<div className="grid gap-4 md:grid-cols-[14rem_minmax(0,1fr)]">
<div className="grid self-start gap-2" role="tablist">
<div className="grid gap-px overflow-hidden rounded-xl border border-white/[0.08] bg-white/[0.08] md:grid-cols-[15rem_minmax(0,1fr)]">
<div
className="grid grid-cols-3 gap-px bg-white/[0.08] md:grid-cols-1 md:content-start md:bg-background"
role="tablist"
>
{AUTOMATION_OPTIONS.map((option) => (
<AutomationSelector
key={option.kind}
@@ -690,17 +726,22 @@ function AutomationSelector({
role="tab"
aria-selected={active}
onClick={handleClick}
className={`flex items-center gap-3 rounded-xl border p-3 text-left transition-colors md:block md:p-4 ${
className={`cursor-pointer border-b-2 p-3.5 text-left transition-colors md:border-b md:border-b-white/[0.07] md:border-l-2 md:p-5 ${
active
? "border-white/20 bg-white/[0.07]"
: "border-white/10 bg-white/[0.025] hover:border-white/15 hover:bg-white/[0.04]"
? "border-b-brand-green bg-white/[0.045] md:border-l-brand-green"
: "border-b-transparent bg-background hover:bg-white/[0.025] md:border-l-transparent"
}`}
>
<div className="flex shrink-0 items-center gap-2 text-muted-foreground md:mb-1">
<Icon className="h-3 w-3" strokeWidth={1.5} />
<span className="text-[10px]">{option.label}</span>
<div className="flex shrink-0 items-center gap-2 font-mono md:mb-1.5">
<Icon
className={`h-3.5 w-3.5 ${active ? "text-accent-text" : "text-muted-foreground"}`}
strokeWidth={1.5}
/>
<span className={`text-[11px] ${active ? "text-accent-text" : "text-muted-foreground"}`}>
{option.label}
</span>
</div>
<p className="text-xs leading-snug text-white/85 md:text-sm">
<p className="mt-1 text-xs leading-snug text-white/85 md:mt-0 md:text-sm">
{t(`landing.automation.${option.kind}Caption`)}
</p>
</button>
@@ -711,7 +752,7 @@ function AutomationDetail({ kind }: { kind: AutomationKind }) {
return (
<div
role="tabpanel"
className="min-h-80 min-w-0 overflow-hidden rounded-xl border border-white/10 bg-black/20 p-5 md:h-[26rem] md:p-6"
className="min-h-80 min-w-0 overflow-hidden bg-[#0c1110] p-5 md:h-[26rem] md:p-6"
>
{kind === "mcp" ? <McpAutomationTranscript /> : null}
{kind === "cli" ? <CliAutomationExample /> : null}
@@ -860,37 +901,82 @@ function SdkAutomationExample() {
);
}
function ExtensibleSection() {
function HubSection() {
const { t } = useTranslation();
const localize = useLocalizePath();
return (
<motion.section
initial={FADE_IN_UP}
whileInView={FADE_IN}
viewport={VIEWPORT_60}
transition={EASE_OUT_05}
aria-labelledby="hub-section-heading"
>
<div className="mb-10 space-y-3 md:mb-12">
<h2 id="hub-section-heading">
<PaseoHubLockup size="display" className="h-9 w-auto text-foreground md:h-11" />
<span className="sr-only">{t("hub.title")}</span>
</h2>
<p className="max-w-xl text-base text-pretty text-muted-foreground">
{t("landing.hubSection.description")}
</p>
</div>
<div className="space-y-8">
<HubLandingFlow />
<div className="flex flex-wrap items-center gap-3">
<a href={localize("/hub")} className={PRIMARY_CTA_CLASS}>
{t("landing.hubSection.exploreCta")}
<ArrowRight className="h-4 w-4" aria-hidden="true" />
</a>
<a href={localize("/docs/hub")} className={SECONDARY_CTA_CLASS}>
{t("landing.hubSection.docsCta")}
</a>
</div>
</div>
</motion.section>
);
}
function ExtensibleSection({ pluginCount }: { pluginCount?: number | null }) {
const { t } = useTranslation();
const pluginActions = React.useMemo(() => <PluginActions />, []);
const libraryTitle =
pluginCount && pluginCount > 0
? t("landing.plugins.libraryTitleCount", { count: pluginCount })
: t("landing.plugins.libraryTitle");
return (
<FeatureSection
eyebrow={t("landing.eyebrows.plugins")}
title={t("landing.plugins.title")}
description={t("landing.plugins.description")}
>
<div className="space-y-12">
<div className="space-y-6">
<SelfModifyDemo />
<div className="space-y-6">
<ProductLead
icon={Puzzle}
title={t("landing.plugins.libraryTitle")}
description={t("landing.plugins.libraryDescription")}
actions={pluginActions}
/>
<PluginCategoryLinks />
</div>
<div className="flex flex-col gap-3 sm:flex-row sm:items-center sm:justify-between">
<p className="text-sm text-white/45">{t("landing.plugins.license")}</p>
<a
href="https://github.com/getpaseo/paseo"
target="_blank"
rel="noopener noreferrer"
className="inline-flex shrink-0 items-center gap-2 text-sm text-muted-foreground transition-colors hover:text-foreground"
>
<GitFork className="h-4 w-4" strokeWidth={1.5} />
{t("landing.plugins.fork")}
<ExternalLink className="h-3.5 w-3.5 opacity-70" />
</a>
<div className="overflow-hidden rounded-xl border border-white/[0.08] bg-white/[0.08]">
<div className="space-y-5 bg-background p-6">
<ProductLead
icon={Puzzle}
title={libraryTitle}
description={t("landing.plugins.libraryDescription")}
actions={pluginActions}
/>
<PluginCategoryLinks />
</div>
<div className="flex flex-col gap-3 border-t border-white/[0.08] bg-background px-6 py-4 sm:flex-row sm:items-center sm:justify-between">
<p className="text-sm text-white/50">{t("landing.plugins.license")}</p>
<a
href="https://github.com/getpaseo/paseo"
target="_blank"
rel="noopener noreferrer"
className="inline-flex shrink-0 items-center gap-2 text-sm text-muted-foreground transition-colors hover:text-accent-text"
>
<GitFork className="h-4 w-4" strokeWidth={1.5} />
{t("landing.plugins.fork")}
<ExternalLink className="h-3.5 w-3.5 opacity-70" />
</a>
</div>
</div>
</div>
</FeatureSection>
@@ -956,7 +1042,7 @@ function SelfModifyDemo() {
initial={reduceMotion ? "shown" : "hidden"}
whileInView="shown"
viewport={VIEWPORT_60}
className="grid min-h-[22rem] grid-cols-[minmax(0,1fr)] overflow-hidden rounded-xl border border-white/10 bg-black/20 md:grid-cols-[minmax(0,1fr)_17rem]"
className="grid min-h-[22rem] grid-cols-[minmax(0,1fr)] overflow-hidden rounded-xl border border-white/[0.08] bg-[#0c1110] md:grid-cols-[minmax(0,1fr)_17rem]"
>
<div className="space-y-5 p-5 md:p-6">
<DemoItem step={DEMO_STEPS.prompt}>
@@ -1087,43 +1173,50 @@ function PhilosophySection() {
const { t } = useTranslation();
return (
<FeatureSection
eyebrow={t("landing.eyebrows.openSource")}
title={t("landing.philosophy.title")}
description={t("landing.philosophy.description")}
>
<div className="grid gap-4 sm:grid-cols-2 lg:grid-cols-3">
<HairlineGrid columns="3">
{PRINCIPLES.map((principle) => (
<FeatureCard
<FeatureCell
key={principle.key}
icon={principle.icon}
title={t(`landing.philosophy.${principle.key}Title`)}
description={t(`landing.philosophy.${principle.key}Description`)}
/>
))}
</div>
</HairlineGrid>
</FeatureSection>
);
}
function DownloadActions() {
const platform = useVisitorPlatform();
return (
<div className="mx-auto flex flex-col items-center gap-3 sm:flex-row sm:justify-center">
{isMobilePlatform(platform) ? (
<StoreButton platform={platform} />
) : (
<DesktopDownloadButton platform={platform} />
)}
<div className="flex items-center justify-center gap-3">
{isMobilePlatform(platform) ? <DesktopAppLink /> : <StoreIconLinks />}
<ServerInstallButton />
</div>
</div>
);
}
function GetStarted() {
const { t } = useTranslation();
const localize = useLocalizePath();
const platform = useVisitorPlatform();
return (
<div className="pt-10">
<div className="pt-8">
{/* The primary call to action owns its own row on phones so the small icon
buttons never wrap and orphan one of themselves onto a line alone. It
still hugs its label rather than stretching across the row. */}
<div className="mx-auto flex flex-col items-center gap-3 sm:flex-row sm:justify-center">
{isMobilePlatform(platform) ? (
<StoreButton platform={platform} />
) : (
<DesktopDownloadButton platform={platform} />
)}
<div className="flex items-center justify-center gap-3">
{isMobilePlatform(platform) ? <DesktopAppLink /> : <StoreIconLinks />}
<ServerInstallButton />
</div>
</div>
<DownloadActions />
<div className="flex flex-wrap items-center justify-center gap-x-2 gap-y-1 pt-6">
<span className="text-xs text-muted-foreground">{t("landing.getStarted.supports")}</span>
<div className="flex items-center gap-1">
@@ -1133,7 +1226,7 @@ function GetStarted() {
</div>
<a
href={localize("/agents")}
className="whitespace-nowrap text-xs text-muted-foreground hover:text-foreground transition-colors"
className="whitespace-nowrap text-xs text-muted-foreground transition-colors hover:text-foreground"
>
{t("common.more", { count: ADDITIONAL_AGENT_COUNT })}
</a>
@@ -1142,6 +1235,28 @@ function GetStarted() {
);
}
function ClosingCtaSection() {
const { t } = useTranslation();
return (
<section aria-labelledby="closing-cta-heading" className="text-center">
<div className="mb-6 flex justify-center">
<span className="inline-flex h-12 w-12 items-center justify-center rounded-xl border border-brand-green/40 bg-brand-green/15 text-accent-text">
<PaseoMark className="h-6 w-6" />
</span>
</div>
<SectionOpener
align="center"
eyebrow={t("landing.closingCta.eyebrow")}
headingId="closing-cta-heading"
title={t("landing.closingCta.title")}
description={t("landing.closingCta.description")}
className="mb-8"
/>
<DownloadActions />
</section>
);
}
const PRIMARY_CTA_CLASS =
"inline-flex items-center justify-center gap-2 rounded-lg bg-foreground px-4 py-2.5 text-sm font-medium text-background hover:bg-foreground/90 transition-colors";
const SECONDARY_CTA_CLASS =
@@ -1285,7 +1400,7 @@ function PhoneShowcase() {
const textAnimate = React.useMemo(() => (textInView ? FADE_IN : {}), [textInView]);
return (
<div ref={containerRef} className="flex flex-col items-center pt-4 pb-16 gap-20">
<div ref={containerRef} className="flex flex-col items-center gap-14 pt-2 pb-12 md:pb-16">
{/* Arrow + text */}
<motion.div
initial={FADE_IN_UP_TINY}
@@ -1397,21 +1512,26 @@ function FAQ() {
[localize],
);
return (
<motion.div
<motion.section
initial={FADE_IN_UP}
whileInView={FADE_IN}
viewport={VIEWPORT_60}
transition={EASE_OUT_05}
className="space-y-6"
aria-labelledby="home-faq-heading"
className="grid items-start gap-10 lg:grid-cols-[minmax(0,17rem)_minmax(0,1fr)] lg:gap-16"
>
<h2 className="text-3xl font-medium">{t("landing.faq.title")}</h2>
<div className="space-y-6">
<SectionOpener
headingId="home-faq-heading"
title={t("landing.faq.title")}
className="mb-0 self-start"
/>
<div className="divide-y divide-white/[0.08] border-y border-white/[0.08]">
{FAQ_ENTRIES.map((entry) => (
<FAQItem key={entry} question={t(`landing.faq.${entry}Question`)}>
<Trans i18nKey={`landing.faq.${entry}Answer`} components={links} />
</FAQItem>
))}
</div>
</motion.div>
</motion.section>
);
}
@@ -0,0 +1,230 @@
import { ExternalLink } from "lucide-react";
import type * as React from "react";
import { SiteHeader } from "~/components/site-header";
/** Shared outer container width. Uses a transparent md:border-x when unframed to avoid a 1px shift. */
export const PAGE_CONTAINER_CLASS =
"mx-auto w-full max-w-[1160px] md:border-x md:border-transparent";
/** Shared outer rail width and vertical hairlines across marketing pages. */
export const PAGE_RAIL_CLASS = "mx-auto w-full max-w-[1160px] md:border-x md:border-white/[0.07]";
/** Shared inner horizontal padding so every page element shares one left/right rail. */
export const PAGE_INSET_CLASS = "px-5 sm:px-8 md:px-14";
/** Extend scrollable content from the mobile inset to the viewport edges. */
export const MOBILE_PAGE_BLEED_CLASS = "-mx-5 px-5";
/** Full-width header band locking logo and navigation to the same (x, y) across pages. */
export function PageHeaderBand({ framed = false }: { framed?: boolean }) {
return (
<div className={framed ? "border-b border-white/[0.07]" : ""}>
<div
className={`${framed ? PAGE_RAIL_CLASS : PAGE_CONTAINER_CLASS} ${PAGE_INSET_CLASS} py-4 md:py-5`}
>
<SiteHeader />
</div>
</div>
);
}
const BAND_PADDING = {
chapter: "py-16 md:py-24",
section: "py-14 md:py-20",
compact: "py-12 md:py-16",
hero: "pt-12 pb-14 md:pt-16 md:pb-20",
none: "",
} as const;
/**
* A full-width architectural band separated by a 1px horizontal hairline with quiet crosshair
* ticks where the horizontal rule meets the vertical frame rails.
*/
export function ChapterBand({
children,
spacing = "chapter",
ruled = true,
ticks = true,
framed = true,
tint = "none",
className = "",
id,
}: {
children: React.ReactNode;
spacing?: keyof typeof BAND_PADDING;
ruled?: boolean;
ticks?: boolean;
framed?: boolean;
tint?: "none" | "subtle";
className?: string;
id?: string;
}) {
return (
<div
id={id}
className={`overflow-x-clip ${ruled ? "border-t border-white/[0.07]" : ""} ${
tint === "subtle" ? "bg-white/[0.014]" : ""
} ${className}`}
>
<div
className={`relative ${framed ? PAGE_RAIL_CLASS : PAGE_CONTAINER_CLASS} ${PAGE_INSET_CLASS} ${BAND_PADDING[spacing]}`}
>
{ruled && ticks && framed ? <RailIntersectionTicks /> : null}
{children}
</div>
</div>
);
}
/** Quiet 9px hairlines centered on the left and right vertical rail intersections. */
function RailIntersectionTicks() {
return (
<>
<span
aria-hidden="true"
className="pointer-events-none absolute -top-[4.5px] -left-[4.5px] hidden h-[9px] w-[9px] md:block"
>
<span className="absolute top-1/2 left-0 h-px w-full -translate-y-1/2 bg-white/25" />
<span className="absolute top-0 left-1/2 h-full w-px -translate-x-1/2 bg-white/25" />
</span>
<span
aria-hidden="true"
className="pointer-events-none absolute -top-[4.5px] -right-[4.5px] hidden h-[9px] w-[9px] md:block"
>
<span className="absolute top-1/2 left-0 h-px w-full -translate-y-1/2 bg-white/25" />
<span className="absolute top-0 left-1/2 h-full w-px -translate-x-1/2 bg-white/25" />
</span>
</>
);
}
/** Internal sub-section divider inside a multi-part chapter, staying inside the frame rails. */
export function ChapterDivider({ className = "" }: { className?: string }) {
return (
<div
aria-hidden="true"
className={`-mx-5 border-t border-white/[0.07] sm:-mx-8 md:-mx-14 ${className}`}
/>
);
}
/**
* Unified section opener used across `/` and `/hub`:
* mono uppercase green eyebrow -> commanding 44px H2 -> concise lede + optional external links.
*/
export function SectionOpener({
eyebrow,
title,
mutedLead,
description,
headingId,
badge,
links,
actions,
align = "left",
className = "mb-10 md:mb-12",
}: {
eyebrow?: string;
title: React.ReactNode;
mutedLead?: string;
description?: React.ReactNode;
headingId?: string;
badge?: string;
links?: ReadonlyArray<{ href: string; label: string }>;
actions?: React.ReactNode;
align?: "left" | "center";
className?: string;
}) {
const centered = align === "center";
return (
<div
className={`${className} ${
centered
? "mx-auto max-w-2xl text-center"
: "flex flex-col gap-5 md:flex-row md:items-end md:justify-between"
}`}
>
<div className={`space-y-3 ${centered ? "" : "max-w-2xl"}`}>
{eyebrow ? (
<p className="font-mono text-[11px] font-medium uppercase tracking-[0.14em] text-accent-text">
{eyebrow}
</p>
) : null}
<div className={`flex flex-wrap items-center gap-3 ${centered ? "justify-center" : ""}`}>
<h2
id={headingId}
className="font-display text-3xl font-semibold tracking-[-0.025em] leading-[1.1] text-foreground sm:text-4xl md:text-[42px]"
>
{mutedLead ? (
<>
<span className="text-white/45">{mutedLead}</span>{" "}
</>
) : null}
{title}
</h2>
{badge ? (
<span className="rounded-full border border-brand-green/40 bg-brand-green/20 px-2.5 py-0.5 text-xs text-accent-text">
{badge}
</span>
) : null}
</div>
{description ? (
<p
className={`text-base leading-relaxed text-pretty text-muted-foreground ${
centered ? "mx-auto max-w-lg" : "max-w-xl"
}`}
>
{description}
</p>
) : null}
{links && links.length > 0 ? (
<div className="flex flex-wrap gap-x-5 gap-y-1.5 pt-1 text-xs">
{links.map((link) => (
<a
key={link.href}
href={link.href}
target="_blank"
rel="noopener noreferrer"
className="inline-flex items-center gap-1 font-mono text-white/55 transition-colors hover:text-accent-text"
>
{link.label}
<ExternalLink className="h-3 w-3" />
</a>
))}
</div>
) : null}
</div>
{actions ? <div className="flex shrink-0 flex-wrap items-center gap-3">{actions}</div> : null}
</div>
);
}
const GRID_COLUMNS = {
"2": "grid-cols-1 lg:grid-cols-2",
"3": "grid-cols-1 md:grid-cols-3",
"2-3": "grid-cols-2 sm:grid-cols-3",
} as const;
/**
* Hairline-divided shared-border cell grid. Uses 1px background gap so interior hairlines never
* double up across responsive column counts.
*/
export function HairlineGrid({
children,
columns = "3",
className = "",
clipContents = true,
}: {
children: React.ReactNode;
columns?: keyof typeof GRID_COLUMNS;
className?: string;
clipContents?: boolean;
}) {
return (
<div
className={`grid gap-px rounded-xl border border-white/[0.08] bg-white/[0.08] ${clipContents ? "overflow-hidden" : ""} ${GRID_COLUMNS[columns]} ${className}`}
>
{children}
</div>
);
}
@@ -50,6 +50,16 @@ describe("paseo brand assets", () => {
}
});
it("tightens symbol-to-wordmark spacing for display-scale lockups while keeping canonical paths", () => {
const html = renderToStaticMarkup(<PaseoHubLockup size="display" className="h-12 w-auto" />);
const canonical = readFileSync(path.join(BRAND_ROOT, "lockups/paseo-hub-white.svg"), "utf8");
expect(html).toContain('viewBox="0 0 798 144"');
expect(html).toContain('width="798"');
expect(html).toContain('transform="translate(-44 0)"');
expect(extractPathData(html)).toEqual(extractPathData(canonical));
});
it("keeps public/logo.svg and public/favicon.svg aligned with assets/brand", () => {
const canonicalPaseo = readFileSync(path.join(BRAND_ROOT, "marks/paseo-white.svg"), "utf8");
const publicLogo = readFileSync(path.join(WEBSITE_PUBLIC, "logo.svg"), "utf8");
+30 -14
View File
@@ -99,22 +99,34 @@ function BrandMark({ asset, props }: { asset: ParsedMark; props: React.SVGProps<
);
}
function BrandLockup({
asset,
props,
}: {
asset: ParsedLockup;
props: React.SVGProps<SVGSVGElement>;
}) {
/**
* Optical horizontal tightening (in 144-unit lockup coordinates) for display-scale lockups.
* Canonical lockups have a ~91-unit ink-to-ink gap calibrated for ~18–22px header sizes; at
* 36–48px display sizes that gap reads ~25–30px wide, so `size="display"` pulls the wordmark
* 44 units closer (~14–16px visual gap, ~1/3 of the mark width) and trims the viewBox to match.
*/
const DISPLAY_GAP_TIGHTEN_UNITS = 44;
export interface BrandLockupProps extends React.SVGProps<SVGSVGElement> {
/** Optical spacing scale: `"default"` for small UI/header lockups, `"display"` for large headings. */
size?: "default" | "display";
}
function BrandLockup({ asset, props }: { asset: ParsedLockup; props: BrandLockupProps }) {
const { size = "default", ...svgProps } = props;
const tighten = size === "display" ? DISPLAY_GAP_TIGHTEN_UNITS : 0;
const width = asset.width - tighten;
const viewBox = tighten > 0 ? `0 0 ${width} ${asset.height}` : asset.viewBox;
return (
<svg
xmlns="http://www.w3.org/2000/svg"
width={asset.width}
width={width}
height={asset.height}
viewBox={asset.viewBox}
viewBox={viewBox}
fill="none"
aria-hidden="true"
{...props}
{...svgProps}
>
<path
d={asset.path}
@@ -123,7 +135,11 @@ function BrandLockup({
strokeLinecap="round"
strokeLinejoin="round"
/>
<path d={asset.wordmarkPath} fill="currentColor" />
<path
d={asset.wordmarkPath}
fill="currentColor"
transform={tighten > 0 ? `translate(-${tighten} 0)` : undefined}
/>
</svg>
);
}
@@ -139,16 +155,16 @@ export function PaseoHubMark(props: React.SVGProps<SVGSVGElement>) {
}
/** Canonical Paseo lockup (butterfly mark at 94% optical scale + Plus Jakarta Sans SemiBold). */
export function PaseoLockup(props: React.SVGProps<SVGSVGElement>) {
export function PaseoLockup(props: BrandLockupProps) {
return <BrandLockup asset={PASEO_LOCKUP} props={props} />;
}
/** Canonical Paseo Hub lockup (flower mark + Plus Jakarta Sans SemiBold). */
export function PaseoHubLockup(props: React.SVGProps<SVGSVGElement>) {
export function PaseoHubLockup(props: BrandLockupProps) {
return <BrandLockup asset={PASEO_HUB_LOCKUP} props={props} />;
}
/** Canonical Hub lockup (flower mark + "Hub"), used where Paseo is already on screen. */
export function HubLockup(props: React.SVGProps<SVGSVGElement>) {
export function HubLockup(props: BrandLockupProps) {
return <BrandLockup asset={HUB_LOCKUP} props={props} />;
}
+87 -63
View File
@@ -1,9 +1,10 @@
import { useTranslation } from "react-i18next";
import { PLUGINS_LINKED } from "~/plugins/launch";
import { PAGE_INSET_CLASS, PAGE_RAIL_CLASS } from "~/components/page-frame";
import { SponsorsSection } from "~/components/sponsorship";
import { getAlternativePages } from "~/data/alternative-pages";
import { appStoreUrl, playStoreUrl, webAppUrl } from "~/downloads";
import { SponsorsSection } from "~/components/sponsorship";
import { useLocale, useLocalizePath } from "~/i18n";
import { PLUGINS_LINKED } from "~/plugins/launch";
interface SiteFooterProps {
width?: "default" | "prose" | "wide";
@@ -11,13 +12,17 @@ interface SiteFooterProps {
sponsors?: boolean;
}
const WIDTH_CLASSES: Record<NonNullable<SiteFooterProps["width"]>, string> = {
const NON_DEFAULT_WIDTH_CLASSES: Record<
Exclude<NonNullable<SiteFooterProps["width"]>, "default">,
string
> = {
prose: "max-w-prose p-6 md:p-12 md:pt-0",
default: "max-w-5xl p-6 md:p-20 md:pt-0",
wide: "max-w-7xl p-6 md:p-20 md:pt-0",
};
const LINK_CLASS = "block text-muted-foreground hover:text-foreground transition-colors";
const LINK_CLASS = "block text-muted-foreground transition-colors hover:text-foreground";
const COLUMN_HEADING_CLASS =
"font-mono text-[11px] uppercase tracking-[0.12em] text-extra-muted-foreground";
function ExternalLink({ href, children }: { href: string; children: React.ReactNode }) {
return (
@@ -31,72 +36,91 @@ export function SiteFooter({ width = "default", sponsors = true }: SiteFooterPro
const { t } = useTranslation();
const locale = useLocale();
const localize = useLocalizePath();
const widthClasses = WIDTH_CLASSES[width];
const alternatives = getAlternativePages(locale);
const page = (path: string, label: string) => (
<a href={localize(path)} className={LINK_CLASS}>
{label}
</a>
);
return (
<footer className={`${widthClasses} mx-auto mt-12 md:mt-16`}>
{sponsors ? <SponsorsSection placement="footer" /> : null}
<div className="border-t border-white/10 pt-8 pb-4 grid grid-cols-2 sm:grid-cols-5 gap-8 text-sm">
<div className="space-y-3">
<p className="text-extra-muted-foreground">{t("footer.product")}</p>
<div className="space-y-2">
{page("/blog", t("footer.blog"))}
{page("/docs", t("footer.docs"))}
{PLUGINS_LINKED && page("/plugins", t("footer.plugins"))}
{page("/changelog", t("footer.changelog"))}
{page("/hub", t("footer.hub"))}
{page("/docs/cli", t("footer.cli"))}
{page("/privacy", t("footer.privacy"))}
{page("/terms", t("footer.terms"))}
{page("/sponsor", t("footer.sponsor"))}
</div>
</div>
<div className="space-y-3">
<p className="text-extra-muted-foreground">{t("footer.agents")}</p>
<div className="space-y-2">
{page("/claude-code", "Claude Code")}
{page("/codex", "Codex")}
{page("/opencode", "OpenCode")}
{page("/antigravity", "Antigravity")}
{page("/muse-code", "Muse Code")}
{page("/agents", t("footer.allProviders"))}
</div>
</div>
<div className="space-y-3">
<p className="text-extra-muted-foreground">{t("footer.alternatives")}</p>
<div className="space-y-2">
{alternatives.map((alternative) => (
<a key={alternative.slug} href={localize(alternative.href)} className={LINK_CLASS}>
{alternative.name}
</a>
))}
</div>
</div>
<div className="space-y-3">
<p className="text-extra-muted-foreground">{t("footer.community")}</p>
<div className="space-y-2">
<ExternalLink href="https://discord.gg/jz8T2uahpH">Discord</ExternalLink>
<ExternalLink href="https://www.reddit.com/r/PaseoAI/">Reddit</ExternalLink>
<ExternalLink href="https://github.com/getpaseo/paseo">GitHub</ExternalLink>
</div>
</div>
<div className="space-y-3">
<p className="text-extra-muted-foreground">{t("footer.download")}</p>
<div className="space-y-2">
<ExternalLink href={appStoreUrl}>App Store</ExternalLink>
<ExternalLink href={playStoreUrl}>Google Play</ExternalLink>
<ExternalLink href="https://github.com/getpaseo/paseo/releases">
{t("footer.desktop")}
</ExternalLink>
<ExternalLink href={webAppUrl}>{t("footer.webApp")}</ExternalLink>
</div>
const columns = (
<div className="grid grid-cols-2 gap-8 text-sm sm:grid-cols-5">
<div className="space-y-3">
<p className={COLUMN_HEADING_CLASS}>{t("footer.product")}</p>
<div className="space-y-2">
{page("/blog", t("footer.blog"))}
{page("/docs", t("footer.docs"))}
{PLUGINS_LINKED && page("/plugins", t("footer.plugins"))}
{page("/changelog", t("footer.changelog"))}
{page("/hub", t("footer.hub"))}
{page("/docs/cli", t("footer.cli"))}
{page("/privacy", t("footer.privacy"))}
{page("/terms", t("footer.terms"))}
{page("/sponsor", t("footer.sponsor"))}
</div>
</div>
<div className="space-y-3">
<p className={COLUMN_HEADING_CLASS}>{t("footer.agents")}</p>
<div className="space-y-2">
{page("/claude-code", "Claude Code")}
{page("/codex", "Codex")}
{page("/opencode", "OpenCode")}
{page("/antigravity", "Antigravity")}
{page("/muse-code", "Muse Code")}
{page("/agents", t("footer.allProviders"))}
</div>
</div>
<div className="space-y-3">
<p className={COLUMN_HEADING_CLASS}>{t("footer.alternatives")}</p>
<div className="space-y-2">
{alternatives.map((alternative) => (
<a key={alternative.slug} href={localize(alternative.href)} className={LINK_CLASS}>
{alternative.name}
</a>
))}
</div>
</div>
<div className="space-y-3">
<p className={COLUMN_HEADING_CLASS}>{t("footer.community")}</p>
<div className="space-y-2">
<ExternalLink href="https://discord.gg/jz8T2uahpH">Discord</ExternalLink>
<ExternalLink href="https://www.reddit.com/r/PaseoAI/">Reddit</ExternalLink>
<ExternalLink href="https://github.com/getpaseo/paseo">GitHub</ExternalLink>
</div>
</div>
<div className="space-y-3">
<p className={COLUMN_HEADING_CLASS}>{t("footer.download")}</p>
<div className="space-y-2">
<ExternalLink href={appStoreUrl}>App Store</ExternalLink>
<ExternalLink href={playStoreUrl}>Google Play</ExternalLink>
<ExternalLink href="https://github.com/getpaseo/paseo/releases">
{t("footer.desktop")}
</ExternalLink>
<ExternalLink href={webAppUrl}>{t("footer.webApp")}</ExternalLink>
</div>
</div>
</div>
);
if (width === "default") {
return (
<footer className="border-t border-white/[0.07]">
{sponsors ? (
<div className="border-b border-white/[0.07]">
<div className={`${PAGE_RAIL_CLASS} ${PAGE_INSET_CLASS}`}>
<SponsorsSection placement="footer" />
</div>
</div>
) : null}
<div className={`${PAGE_RAIL_CLASS} ${PAGE_INSET_CLASS} py-12 md:py-14`}>{columns}</div>
</footer>
);
}
return (
<footer className={`${NON_DEFAULT_WIDTH_CLASSES[width]} mx-auto mt-12 md:mt-16`}>
{sponsors ? <SponsorsSection placement="footer" /> : null}
<div className="border-t border-white/10 pt-8 pb-4">{columns}</div>
</footer>
);
}
@@ -22,7 +22,7 @@ export function SiteHeader() {
>
<PaseoLockup className="h-[22px] w-auto" />
</a>
<div className="flex flex-wrap items-center justify-center gap-4">
<nav className="flex flex-wrap items-center justify-center gap-4">
{PLUGINS_LINKED && (
<a href={localize("/plugins")} className={NAV_LINK_CLASS}>
{t("nav.plugins")}
@@ -63,7 +63,7 @@ export function SiteHeader() {
<GitHubIcon width="18" height="18" />
{stars && <span className="text-sm">{stars}</span>}
</a>
</div>
</nav>
</header>
);
}
+14 -5
View File
@@ -1,4 +1,5 @@
import type { ReactNode } from "react";
import { PAGE_INSET_CLASS, PAGE_RAIL_CLASS, PageHeaderBand } from "~/components/page-frame";
import { SiteFooter } from "~/components/site-footer";
import { SiteHeader } from "~/components/site-header";
@@ -7,18 +8,26 @@ interface SiteShellProps {
width: "default" | "prose" | "wide";
}
const MAIN_CLASSES: Record<SiteShellProps["width"], string> = {
const MAIN_CLASSES: Record<Exclude<SiteShellProps["width"], "default">, string> = {
prose: "max-w-prose p-6 md:p-12 mx-auto",
default: "max-w-5xl p-6 md:p-20 mx-auto",
wide: "max-w-7xl p-6 md:p-20 mx-auto",
};
export function SiteShell({ children, width }: SiteShellProps) {
const mainClasses = MAIN_CLASSES[width];
if (width === "default") {
return (
<div className="min-h-screen bg-background">
<PageHeaderBand framed />
<main className={`${PAGE_RAIL_CLASS} ${PAGE_INSET_CLASS} py-14 md:py-20`}>{children}</main>
<SiteFooter width="default" />
</div>
);
}
return (
<div className="min-h-screen bg-background">
<main className={mainClasses}>
<div className="mb-20">
<main className={MAIN_CLASSES[width]}>
<div className="mb-16">
<SiteHeader />
</div>
{children}
+91 -28
View File
@@ -1,8 +1,8 @@
import { ArrowRight, Check, ExternalLink, Heart } from "lucide-react";
import * as React from "react";
import { Trans, useTranslation } from "react-i18next";
import { useLocalizePath } from "~/i18n";
import { BuyMeACoffeeIcon, GitHubIcon, OpenCollectiveIcon } from "~/components/brand-icons";
import { HairlineGrid, SectionOpener } from "~/components/page-frame";
import {
BUY_ME_A_COFFEE_URL,
GITHUB_SPONSORS_URL,
@@ -14,6 +14,7 @@ import {
openSpotCount,
sponsorHref,
} from "~/data/sponsors";
import { useLocalizePath } from "~/i18n";
function SectionHeading({
as: Heading,
@@ -27,11 +28,13 @@ function SectionHeading({
badge?: string;
}) {
return (
<div className="mb-12 space-y-2">
<div className="mb-10 space-y-2.5">
<div className="flex items-center gap-3">
<Heading className="text-3xl font-medium tracking-tight">{title}</Heading>
<Heading className="font-display text-3xl font-semibold tracking-[-0.025em] md:text-[42px]">
{title}
</Heading>
{badge ? (
<span className="rounded-full bg-emerald-400/10 px-2 py-1 text-xs text-emerald-300">
<span className="rounded-full border border-brand-green/40 bg-brand-green/20 px-2.5 py-0.5 text-xs text-accent-text">
{badge}
</span>
) : null}
@@ -55,7 +58,7 @@ const MAINTAINER_COMPONENTS = {
};
const MAINTAINER_SIGNATURE = (
<p className="text-white/50">
<p className="text-sm text-white/50">
<Trans i18nKey="sponsor.maintainer" components={MAINTAINER_COMPONENTS} />
</p>
);
@@ -141,26 +144,28 @@ export function BackingOptions() {
[localize, t],
);
return (
<div className="grid gap-3 md:grid-cols-2">
<HairlineGrid columns="2">
{options.map((option) => (
<a
key={option.href}
href={option.href}
{...(option.external ? { target: "_blank", rel: "noopener noreferrer" } : {})}
className="flex items-center gap-4 rounded-xl border border-white/10 bg-white/[0.02] p-4 transition-colors hover:border-white/20 hover:bg-white/[0.05]"
className="group flex items-center justify-between gap-4 bg-background px-5 py-4 transition-colors hover:bg-white/[0.03]"
>
<option.icon className="h-6 w-6 shrink-0 text-white/60" />
<p className="flex items-center gap-1.5 font-medium text-white">
{option.name}
{option.external ? (
<ExternalLink className="h-3.5 w-3.5 text-white/40" />
) : (
<ArrowRight className="h-3.5 w-3.5 text-white/40" />
)}
</p>
<span className="flex items-center gap-3.5">
<option.icon className="h-5 w-5 shrink-0 text-white/60 transition-colors group-hover:text-white/90" />
<span className="text-sm font-medium text-white/90 group-hover:text-white">
{option.name}
</span>
</span>
{option.external ? (
<ExternalLink className="h-3.5 w-3.5 shrink-0 text-white/35 transition-colors group-hover:text-accent-text" />
) : (
<ArrowRight className="h-3.5 w-3.5 shrink-0 text-white/35 transition-colors group-hover:text-accent-text" />
)}
</a>
))}
</div>
</HairlineGrid>
);
}
@@ -184,7 +189,7 @@ export function SponsorSpotSection() {
<ul className="grid max-w-2xl gap-3 text-white/70">
{SPOT_FEATURES.map((feature) => (
<li key={feature} className="flex items-start gap-2.5">
<Check aria-hidden="true" className="mt-1 size-4 shrink-0 text-emerald-300" />
<Check aria-hidden="true" className="mt-1 size-4 shrink-0 text-accent-text" />
<span>{t(`sponsor.company.${feature}`)}</span>
</li>
))}
@@ -193,7 +198,7 @@ export function SponsorSpotSection() {
{open > 0 ? (
<a
href={SPONSOR_SPOT_CHECKOUT_URL}
className="inline-flex items-center rounded-md bg-white px-5 py-2.5 text-sm font-medium text-black transition-colors hover:bg-white/90"
className="inline-flex items-center rounded-lg bg-foreground px-5 py-2.5 text-sm font-medium text-background transition-colors hover:bg-foreground/90"
>
{t("sponsor.becomeSponsor")}
</a>
@@ -224,15 +229,72 @@ export function SponsorPaseoSection() {
);
}
/** Homepage: a short version of the note with the same links as /sponsor. */
/** Standalone short sponsor note + backing options (used on /download/thanks). */
export function SponsorSection() {
const { t } = useTranslation();
const hubLink = useHubLinkComponents();
return (
<section>
<SectionHeading as="h2" title={t("sponsor.title")} />
<div className="space-y-10">
<div className="max-w-2xl space-y-5 leading-relaxed text-white/70">
<div className="space-y-8">
<div className="max-w-2xl space-y-4 text-sm leading-relaxed text-white/70">
<p>{t("sponsor.note.independent")}</p>
<p>{t("sponsor.shortNote.maintained")}</p>
<p>
<Trans i18nKey="sponsor.shortNote.selfFunded" components={hubLink} />
</p>
{MAINTAINER_SIGNATURE}
</div>
<BackingOptions />
</div>
</section>
);
}
/**
* Consolidated homepage Sponsors + Sponsor Paseo section.
* Keeps `aria-labelledby="sponsors-heading"` with heading text "Sponsors" so the Sponsors region
* contract stays intact while unifying the logo row, founder note, and backing options into one
* coherent chapter.
*/
export function HomepageSponsorsSection() {
const { t } = useTranslation();
const localize = useLocalizePath();
const hubLink = useHubLinkComponents();
const open = openSpotCount();
return (
<section aria-labelledby="sponsors-heading">
<SectionOpener headingId="sponsors-heading" title={t("sponsor.sponsors")} className="mb-10" />
<ul className="flex flex-wrap items-center gap-x-14 gap-y-8">
{SPONSORS.map((sponsor) => (
<li key={sponsor.url}>
<a
href={sponsorHref(sponsor, "website")}
target="_blank"
rel="noopener noreferrer"
className="block"
>
<img src={sponsor.logo.onDark} alt={sponsor.name} className="h-12 w-auto" />
</a>
<p className="mt-2 text-sm text-white/55">{sponsor.description}</p>
</li>
))}
{open > 0 ? (
<li>
<a
href={localize("/sponsor#spot")}
className="inline-flex h-11 items-center rounded-lg border border-dashed border-white/15 px-4 text-sm text-white/50 transition-colors hover:border-white/30 hover:text-white/80"
>
{t("sponsor.becomeSponsor")}
</a>
</li>
) : null}
</ul>
<div className="mt-10 grid gap-10 border-t border-white/[0.07] pt-10 lg:grid-cols-[minmax(0,1fr)_minmax(0,1fr)] lg:items-start">
<div className="space-y-4 text-sm leading-relaxed text-white/70">
<p>{t("sponsor.note.independent")}</p>
<p>{t("sponsor.shortNote.maintained")}</p>
<p>
@@ -257,18 +319,19 @@ const SPONSORS_PLACEMENTS = {
button: "h-12 px-5 text-sm",
},
footer: {
section: "space-y-5 border-t border-white/10 py-8",
heading: "gap-1.5 text-sm text-extra-muted-foreground",
section: "space-y-5 py-8",
heading:
"gap-1.5 font-mono text-[11px] uppercase tracking-[0.12em] text-extra-muted-foreground",
heart: "size-3",
link: "opacity-85 transition-opacity hover:opacity-100",
logo: "h-10",
logo: "h-9",
description: "mt-1.5 text-xs text-white/45",
button: "h-9 px-3.5 text-sm",
button: "h-9 px-3.5 text-xs",
},
} as const;
interface SponsorsSectionProps {
/** `page` is a homepage section; `footer` is the band above other pages' footers. */
/** `page` is a standalone section; `footer` is the band above other pages' footers. */
placement: keyof typeof SPONSORS_PLACEMENTS;
}
@@ -313,7 +376,7 @@ export function SponsorsSection({ placement }: SponsorsSectionProps) {
<li>
<a
href={localize("/sponsor#spot")}
className={`inline-flex items-center rounded-md border border-dashed border-white/15 text-white/45 transition-colors hover:border-white/30 hover:text-white/75 ${style.button}`}
className={`inline-flex items-center rounded-lg border border-dashed border-white/15 text-white/45 transition-colors hover:border-white/30 hover:text-white/75 ${style.button}`}
>
{t("sponsor.becomeSponsor")}
</a>
+8
View File
@@ -166,6 +166,14 @@ export function getLegacyDocsRedirect(pathname: string): string | undefined {
const provider = /^\/docs\/(claude-code|codex|muse-code)(\.md)?\/?$/.exec(pathname);
if (provider) return `/docs/supported-providers/${provider[1]}${provider[2] ?? ""}`;
// Legacy Hub stepped-workflow docs moved to self-contained trigger docs and YAML reference.
const hubLegacy = /^\/docs\/hub\/(workflows|configuration\/hub-yml)(\.md)?\/?$/.exec(pathname);
if (hubLegacy) {
const target =
hubLegacy[1] === "workflows" ? "/docs/hub/triggers" : "/docs/hub/configuration/reference";
return `${target}${hubLegacy[2] ?? ""}`;
}
const match =
/^\/docs\/plugins\/v0\.[78](?:(\.md)|\/(index|reference|providers|migration)(\.md)?)?\/?$/.exec(
pathname,
+25 -12
View File
@@ -43,25 +43,38 @@ async function writeCachedValue<T>(
);
}
export async function getBlockingColdCache<T>({
context,
key,
isValue,
fetchFresh,
}: {
interface CacheOptions<T> {
context: WebsiteCacheContext;
key: string;
isValue: Validator<T>;
fetchFresh: () => Promise<T>;
}): Promise<T> {
}
function refreshInBackground<T>({ context, key, fetchFresh }: CacheOptions<T>): void {
context.waitUntil(
fetchFresh()
.then((fresh) => writeCachedValue(context.cache, key, fresh))
.catch(() => undefined),
);
}
/** Return the cached value, warming the cache in the background when it is empty or stale. */
export async function getNonBlockingColdCache<T>(options: CacheOptions<T>): Promise<T | null> {
const { context, key, isValue } = options;
if (!context.cache) return null;
const cached = await readCachedValue(context.cache, key, isValue);
if (!cached || Date.now() - cached.fetchedAt > GITHUB_CACHE_TTL_MS) {
refreshInBackground(options);
}
return cached?.value ?? null;
}
export async function getBlockingColdCache<T>(options: CacheOptions<T>): Promise<T> {
const { context, key, isValue, fetchFresh } = options;
const cached = await readCachedValue(context.cache, key, isValue);
if (cached) {
if (Date.now() - cached.fetchedAt > GITHUB_CACHE_TTL_MS) {
context.waitUntil(
fetchFresh()
.then((fresh) => writeCachedValue(context.cache, key, fresh))
.catch(() => undefined),
);
refreshInBackground(options);
}
return cached.value;
}
+63 -2
View File
@@ -2,12 +2,13 @@ import { readFile, readdir } from "node:fs/promises";
import path from "node:path";
import YAML from "yaml";
import { describe, expect, it } from "vitest";
import { getDoc, getDocs, getLegacyDocsRedirect, parseHeadings } from "./docs";
const repositoryRoot = path.resolve(import.meta.dirname, "../../..");
const hubDocs = path.join(repositoryRoot, "public-docs", "hub");
describe("Hub public documentation examples", () => {
it("parses every Hub YAML example and keeps resource maps canonical", async () => {
it("parses every Hub YAML example and keeps trigger documents canonical", async () => {
const files = [
...(await markdownFiles(hubDocs)),
path.join(repositoryRoot, "public-docs", "cli.md"),
@@ -24,6 +25,9 @@ describe("Hub public documentation examples", () => {
expect(parsed, `${label} must not teach monolithic triggers`).not.toHaveProperty(
"triggers",
);
expect(parsed, `${label} must not teach legacy stepped workflows`).not.toHaveProperty(
"steps",
);
if (Object.hasOwn(parsed, "environments")) {
expect(isRecord(parsed["environments"]), `${label} environments`).toBe(true);
}
@@ -35,18 +39,75 @@ describe("Hub public documentation examples", () => {
expect(exampleCount).toBeGreaterThan(20);
});
it("does not teach removed Hub authoring paths or composition fields", async () => {
it("does not teach removed Hub authoring paths or legacy stepped workflows", async () => {
const markdown = (
await Promise.all((await markdownFiles(hubDocs)).map((file) => readFile(file, "utf8")))
).join("\n");
expect(markdown).not.toContain(".paseo/partials/");
expect(markdown).not.toContain(".paseo/workflows/");
expect(markdown).not.toContain(".paseo/hub.yml");
expect(markdown).not.toMatch(/^triggers:/mu);
expect(markdown).not.toMatch(/^steps:/mu);
expect(markdown).not.toMatch(/^\s+allow_outputs:/mu);
expect(markdown).not.toMatch(/^\s+uses:/mu);
expect(markdown).not.toContain("paseo hub deploy [file]");
});
it.each(["en", "zh-CN"] as const)(
"resolves every internal /docs/hub link and heading anchor in %s",
(locale) => {
const docs = getDocs(locale);
const headingsByHref = new Map(docs.map((doc) => [doc.href, headingIds(doc.content)]));
const hubPages = docs.filter(
(doc) => doc.href === "/docs/hub" || doc.href.startsWith("/docs/hub/"),
);
expect(hubPages.length).toBeGreaterThanOrEqual(25);
const broken: string[] = [];
for (const doc of hubPages) {
for (const match of doc.content.matchAll(/\]\((\/docs\/hub[^)\s]*)\)/gu)) {
const target = match[1] ?? "";
const [rawPath, hash] = target.split("#");
const cleanPath = (rawPath ?? "").replace(/\/$/u, "");
const headings = headingsByHref.get(cleanPath);
if (!headings) {
broken.push(`${doc.sourcePath} -> missing page ${target}`);
} else if (hash && !headings.has(hash)) {
broken.push(`${doc.sourcePath} -> missing anchor ${target}`);
}
}
}
expect(broken).toEqual([]);
},
);
it("redirects removed legacy Hub workflow and hub-yml paths to current pages", () => {
const redirects = [
["/docs/hub/workflows", "/docs/hub/triggers"],
["/docs/hub/configuration/hub-yml", "/docs/hub/configuration/reference"],
] as const;
for (const [legacyPath, targetPath] of redirects) {
expect(getDoc(targetPath.slice("/docs/".length), "en")).toBeDefined();
expect(getDoc(targetPath.slice("/docs/".length), "zh-CN")).toBeDefined();
for (const extension of ["", ".md"]) {
expect(getLegacyDocsRedirect(`${legacyPath}${extension}`)).toBe(
`${targetPath}${extension}`,
);
expect(getLegacyDocsRedirect(`${legacyPath}${extension}/`)).toBe(
`${targetPath}${extension}`,
);
expect(getLegacyDocsRedirect(`${targetPath}${extension}`)).toBeUndefined();
}
}
});
});
function headingIds(content: string): Set<string> {
return new Set(parseHeadings(content).map((heading) => heading.id));
}
function yamlFences(markdown: string): readonly string[] {
return [...markdown.matchAll(/```yaml\s*\n([\s\S]*?)```/gu)].map((match) => match[1] ?? "");
}
+244 -71
View File
@@ -348,6 +348,20 @@
"intro": "Paseo supports many agents natively. It also runs any <acp>ACP agent</acp>, and you can add new providers with <plugins>plugins</plugins>."
},
"landing": {
"hubEyebrow": {
"product": "Paseo Hub",
"label": "Automations on your machines"
},
"eyebrows": {
"providers": "Providers",
"plugins": "Plugins",
"openSource": "Open source"
},
"closingCta": {
"eyebrow": "Get started",
"title": "Your agents, on every screen.",
"description": "Download the desktop app or run the daemon on any machine. Open source under Apache 2.0."
},
"socialProof": {
"title": "Loved by developers",
"description": "See what developers are saying about Paseo",
@@ -369,9 +383,17 @@
"remoteDescription": "Run Paseo on a home lab, or a cloud machine",
"remoteCta": "Docs",
"teamsTitle": "Teams and triggers",
"teamsDescription": "Share access or start work from GitHub, Slack, and Discord",
"teamsDescription": "Share daemons with your team and automate runs with Paseo Hub",
"teamsCta": "Paseo Hub"
},
"hubSection": {
"description": "Run agents on your machines from GitHub, Linear, Slack, Discord, schedules, or webhooks.",
"flowTriggers": "Trigger sources",
"flowDaemons": "Your connected daemons",
"flowOpenSession": "Open live session in Paseo",
"exploreCta": "Explore Paseo Hub",
"docsCta": "Self-host docs"
},
"automation": {
"title": "Built for automation",
"description": "Use MCP, the CLI, or the TypeScript SDK to automate Paseo",
@@ -393,7 +415,9 @@
"plan": "I'll build it as a local plugin and install it.",
"done": "Review queue is in your sidebar.",
"panelTitle": "Review queue",
"libraryTitle": "400+ community plugins",
"libraryTitle": "Community plugins",
"libraryTitleCount_one": "{{count}} community plugin",
"libraryTitleCount_other": "{{count}} community plugins",
"libraryDescription": "Built by developers on the same plugin API your agents use",
"browse": "Browse plugins",
"docs": "Plugin docs",
@@ -580,25 +604,213 @@
"reddit": "Workflows and questions."
},
"hub": {
"metaTitle": "Paseo Hub - GitHub, Slack, and Discord triggers",
"metaDescription": "Run Paseo Hub yourself and start agents on your own machines from GitHub, Slack, and Discord.",
"metaTitle": "Paseo Hub - Agent automations on your machines",
"metaDescription": "Automate the agents on your Paseo daemons from GitHub, Linear, Slack, Discord, schedules, and webhooks. Self-host Hub or use the hosted service.",
"title": "Paseo Hub",
"intro": "An optional service that sits above your daemons and gives them extra capabilities.",
"runIt": "Run it yourself or use the hosted service.",
"intro": "Automate coding agents and share daemons across your team. Every run executes on your own machines.",
"runIt": "Run it yourself under Apache 2.0 or use the hosted service.",
"hero": {
"getStarted": "Get started",
"selfHost": "Self-host"
},
"eyebrows": {
"architecture": "Architecture",
"pricing": "Pricing"
},
"automations": {
"title": "Automations from every source",
"description": "Triggers watch for events across your tools and start agents on your connected daemons."
},
"sources": {
"github": {
"name": "GitHub",
"description": "Issues, pull requests, and comments."
},
"linear": {
"name": "Linear",
"description": "Issues, assignments, and comments."
},
"slack": {
"name": "Slack",
"description": "Mentions in channels and threads."
},
"discord": {
"name": "Discord",
"description": "Mentions in channels and threads."
},
"schedules": {
"name": "Schedules",
"description": "Recurring runs in your timezone."
},
"webhooks": {
"name": "Webhooks",
"description": "Events from any service or script."
}
},
"demo": {
"shared": {
"tablistLabel": "Automation source previews",
"openInPaseo": "Open in Paseo",
"testsPassed": "tests passed",
"appBadge": "APP",
"docsLink": "Read {{source}} docs"
},
"slack": {
"alt": "Slack thread in #engineering showing mo mentioning @paseo-bot to list P0 issues and open a pull request",
"searchPlaceholder": "Search Paseo",
"channels": "Channels",
"apps": "Apps",
"channelTopic": "Core daemon, mobile & Hub",
"threadReplies": "3 replies",
"typing": "paseo-bot is typing...",
"composerPlaceholder": "Reply...",
"showIssues": "<mention/> show me the latest P0 issues",
"issuesOpen": "Three P0 issues are open:",
"createPr": "<mention/> create a pull request for the first one",
"ranOn": "Continued on <host>macbook-pro</host>. Opened <pr>getpaseo/paseo#1234</pr> with a fix for the terminal writes.",
"filesChanged": "3 files changed",
"caption": "Reply in the same thread to steer the running agent, or open the session in Paseo."
},
"github": {
"alt": "GitHub issue #2811 showing mo labeling an issue and paseo-bot opening pull request #2819 with passing checks",
"issueTitle": "Terminal output drops under sustained load",
"issueMeta": "opened this issue 14 minutes ago · 2 comments",
"authorBadge": "Owner",
"botBadge": "bot",
"openedAgo": "14 minutes ago",
"repliedAgo": "9 minutes ago",
"issueBody": "Fast output bursts drop frames when the PTY buffer fills up. <mention/> reproduce this and open a fix.",
"addedLabel": "added the",
"startedOn": "paseo-bot started on macbook-pro",
"botReply": "Reproduced with a 64 KB burst test on <host>macbook-pro</host> and opened <pr>#2819</pr> to bound and drain the write queue.",
"checksPassed": "All 4 checks passed",
"assignees": "Assignees",
"labels": "Labels",
"development": "Development",
"daemon": "Daemon",
"caption": "Label an issue or comment to start an agent on your daemon and open a pull request."
},
"linear": {
"alt": "Linear issue PAS-418 assigned to paseo-bot, running on devbox and linking pull request #2822",
"issueTitle": "Relay reconnect loop on Android after sleep",
"issueDescription": "After the phone wakes from Doze mode, the relay socket retries every 200ms without backoff.",
"activity": "Activity",
"assignedEvent": "assigned this issue to",
"runningOn": "Ran on <host>devbox</host> · Codex",
"traceLine": "Read relay/reconnect.ts, added jittered backoff and wake reset",
"botSummary": "Added exponential backoff with a wake-state reset in <code>relay/reconnect.ts</code> and regression tests. Pull request is ready for review.",
"properties": "Properties",
"status": "Status",
"priority": "Priority",
"assignee": "Assignee",
"creator": "Creator",
"labels": "Labels",
"daemon": "Daemon",
"caption": "Assign an issue to start an agent on your daemon and link the pull request back."
},
"discord": {
"alt": "Discord channel #engineering showing mo mentioning @paseo-bot and receiving a thread reply with pull request #2825",
"textChannels": "Text channels",
"channelTopic": "Daemon & CLI engineering",
"threadTitle": "Fix stale worktrees",
"time1": "Today at 10:12 AM",
"time2": "Today at 10:16 AM",
"userPrompt": "<mention/> fix the stale worktree branch cleanup bug from <issue/>",
"startedThread": "started a thread:",
"botStarted": "Running on <host>devbox</host> with OpenCode. Checking worktree close hooks.",
"botFinished": "Pruned orphaned branches when an agent workspace closes and added a test.",
"fieldHost": "Host",
"fieldDiff": "Changes",
"fieldChecks": "Checks",
"composerPlaceholder": "Message #engineering",
"caption": "Mention @paseo-bot in a channel to run an agent in a thread and report back."
},
"schedules": {
"alt": "Daily CI optimizer schedule running at 7:00 AM on devbox, opening pull request #2831 and posting a summary to Slack",
"active": "Active",
"jobTitle": "Daily CI optimizer",
"cadence": "Weekdays at 7:00 AM America/New_York",
"step1Title": "Scheduled run #42 analyzed the last 24h of CI",
"step1Detail": "Found <code>website-e2e</code> flaking in 18% of runs and cold Rust builds adding 2m 40s.",
"step2Title": "Opened pull request on devbox",
"metricRuntime": "Avg workflow",
"metricFlake": "e2e flake rate",
"metricCache": "Cargo cache",
"slackPosted": "Posted to Slack",
"slackSummary": "Morning CI report: cut average workflow time from <strong>7m 12s</strong> to <strong>4m 28s</strong> and fixed the e2e flake in <pr>#2831</pr>.",
"notifiedMo": "cc @mo",
"caption": "Run agents on a schedule in your timezone, open pull requests, and post to Slack."
},
"webhooks": {
"alt": "A terminal shows a webhook POST. Hub returns 202 Accepted and starts a Codex run on devbox.",
"runMeta": "devbox · Codex · getpaseo/paseo",
"statusDone": "PR opened",
"trace1": "Checked out <code>v0.19.4</code> in an isolated worktree",
"trace2": "Traced <code>ECONNRESET</code> to idle keepalive timeout in <code>relay/server.ts</code>",
"trace3": "Opened <pr/> with fix and regression test, all checks passed",
"triggeredBy": "webhook · sentry-alert",
"routedLine": "Hub routed to devbox · 118ms",
"caption": "Send a POST request from any script or service to start an agent on your daemon."
}
},
"authoring": {
"title": "Configure in the dashboard or ship as code",
"description": "Set up triggers in the browser or commit YAML files to your repository and deploy from the CLI.",
"dashboardTitle": "Dashboard and run activity",
"dashboardDescription": "Pick a daemon and working directory in the browser. Hub checks which providers, models, and modes the daemon offers as you configure a trigger.",
"triggersLabel": "Triggers:",
"triggersText": "Create, edit, or pause automations in form or YAML view.",
"validationLabel": "Live checks:",
"validationText": "See which providers, models, and modes the connected daemon offers.",
"activityLabel": "Run activity:",
"activityText": "Inspect deliveries, routing outcomes, outputs, and errors.",
"docsLink": "Read configuration docs"
},
"shape": {
"title": "Shared with your team, locked to your machines",
"description": "Hub connects to the daemons you already run. Your team shares triggers and history while your code stays on your machines.",
"triggersRow": "Automation sources",
"webhooks": "webhooks, mentions, and schedules",
"hub": "Hub",
"hubHosting": "Self-hosted or hosted",
"sameRpcs": "the same RPCs the app and CLI use",
"daemonsRow": "Your connected daemons",
"directOrRelay": "direct connection or encrypted relay",
"appsRow": "Paseo clients",
"desktop": "Desktop",
"web": "Web",
"mobile": "Mobile",
"cli": "CLI"
},
"guardrails": {
"optInTitle": "Opt-in execution",
"optInDescription": "The <code>hub.execute</code> permission is off by default on every daemon and granted per machine.",
"scopedTitle": "Scoped triggers",
"scopedDescription": "Event triggers support sender allowlists and resource filters. You can set GitHub permissions for each step and scope the Slack and Discord tools.",
"visibilityTitle": "Team visibility",
"visibilityDescription": "Owners, admins, and members share daemons, triggers, run history, and routing outcomes."
},
"agents": {
"title": "Runs the agents you already have",
"description": "Hub discovers the providers on each connected Paseo daemon. You can run Claude Code, Codex, OpenCode, Pi, and custom providers, including those from plugins."
},
"pricing": {
"title": "Choose how to run Hub",
"unavailable": "The plan comparison is temporarily unavailable.",
"selfHost": "Self-host Hub",
"title": "Self-host or hosted",
"seatNote": "Run the open-source Hub yourself under Apache 2.0 or use the hosted service. Hub dashboard members and pending invitations count as seats.",
"unavailable": "The hosted plan comparison is temporarily unavailable.",
"selfHost": "Self-host docs",
"selfHosted": "Self-hosted",
"free": "Free",
"openSource": "/ open source",
"openSource": "/ Apache 2.0",
"getStarted": "Get started",
"operateHub": "You operate Hub",
"operateHub": "Run with <code>npx @getpaseo/hub</code> or Docker Compose",
"allSources": "GitHub, Linear, Slack, Discord, schedules, and webhooks",
"managedSources": "GitHub, Linear, Slack, Discord, schedules, and webhooks",
"ownApps": "Provider apps you create and control",
"openSourceFeature": "Open source",
"openSourceFeature": "Apache 2.0 open source",
"unlimitedRuns": "Unlimited agent runs",
"runsPerMonth": "{{value}} agent runs a month",
"unlimitedUnits": "Unlimited {{unit}}s",
"noSeatCap": "No seat cap",
"units_one": "{{value}} {{unit}}",
"units_other": "{{value}} {{unit}}s",
"perMonth": "/ month",
@@ -607,71 +819,32 @@
"perUnitMonths": "per {{unit}} / {{count}} months",
"seat": "seat"
},
"triggers": {
"title": "Triggers, running on your machines",
"description": "Mention the bot in GitHub, Slack, or Discord and an agent starts on your daemon.",
"github": "Issues, PRs, and reviews.",
"slack": "Channels and threads.",
"discord": "Channels and threads."
},
"demo": {
"showIssues": "<mention/> show me the latest P0 issues",
"issuesOpen": "Three P0 issues are open:",
"createPr": "<mention/> create a pull request for the first one",
"ranOn": "Ran on <host>macbook-pro</host>. Opened <pr>getpaseo/paseo#1234</pr> with a fix for the terminal writes.",
"filesChanged": "3 files changed",
"testsPassed": "tests passed",
"bot": "Bot",
"caption": "The agent ran on your daemon, with your keys."
},
"agents": {
"title": "Runs the agents you already have",
"description": "The Hub ships no agent of its own, so your team works with the providers, subscriptions, and skills already configured on your daemons."
},
"shape": {
"title": "Works with your existing infrastructure",
"description": "The Hub connects to the daemons you already run, and your apps keep connecting to those same daemons.",
"triggersRow": "Triggers and teammates",
"yourTeam": "Your team",
"futureIntegrations": "Future integrations",
"webhooks": "webhooks and mentions",
"hub": "Hub",
"hubHosting": "Self-hosted or managed",
"sameRpcs": "the same RPCs the app and CLI use",
"daemonsRow": "Your daemons",
"directOrRelay": "direct connection or relay",
"appsRow": "Paseo apps",
"desktop": "Desktop",
"web": "Web",
"mobile": "Mobile",
"cli": "CLI"
},
"faq": {
"title": "FAQ",
"whatQuestion": "What is the Hub?",
"whatAnswer": "A separate service that sits above your Paseo daemons. You connect one or more daemons to it and it gives them GitHub, Slack, and Discord triggers, with collaboration features planned. Paseo works fully without it.",
"separateQuestion": "Why is it a separate service instead of part of the daemon?",
"separateAnswer1": "The daemon stays one lean executable on one machine. The Hub talks to daemons over the same RPCs the app and the CLI use, so anyone can build their own hub on top of Paseo.",
"separateAnswer2": "It also has a different job. The Hub is meant to be exposed to the internet, shared with a team, and run multi-tenant. None of that belongs in a single machine daemon.",
"whatQuestion": "What is Paseo Hub?",
"whatAnswer": "Paseo Hub is a separate service that sits above your Paseo daemons. Connect one or more daemons to automate agent runs from GitHub, Linear, Slack, Discord, schedules, and webhooks, and share them with your team. Paseo works on its own without Hub.",
"separateQuestion": "Why is Hub a separate service instead of part of the daemon?",
"separateAnswer1": "The daemon stays a single process on one machine. Hub talks to daemons over the same RPCs that the app and CLI use, so anyone can build another service on top of Paseo.",
"separateAnswer2": "Hub also has a different job. It receives public webhooks, handles team access, and runs multi-tenant. None of that belongs inside a single-machine daemon.",
"selfHostQuestion": "Can I run it myself?",
"selfHostAnswer": "Yes. Run <code>npx @getpaseo/hub</code> and complete setup in the browser. The source is available on <github>GitHub</github>, and the <guide>self-hosting guide</guide> covers more involved deployments.",
"selfHostAnswer": "Yes. Run <code>npx @getpaseo/hub</code> or start it with Docker Compose and finish setup in your browser. The Apache 2.0 source is on <github>GitHub</github>, and the <guide>self-hosting guide</guide> covers production deployments.",
"needQuestion": "What do I need to run it?",
"needAnswer": "Node.js and a running Paseo daemon. Hub guides you through connecting the provider apps you want.",
"needAnswer": "You need Node.js or Docker and a running Paseo daemon. Hub walks you through connecting your daemons and provider apps.",
"hostedQuestion": "Is there a hosted version?",
"hostedAnswer": "Yes. The hosted service runs the same Hub software you can self-host.",
"plannedQuestion": "What else is planned?",
"plannedIntro": "Not built yet, listed so you know where this is going.",
"plannedProvisioning": "Provisioning daemons for your team",
"plannedSharing": "Sharing settings and skills across a team",
"plannedIntegrations": "More integrations",
"hostedAnswer": "Yes. The <hosted>hosted service</hosted> runs the same open-source Hub software that you can self-host. Hub dashboard members and pending invitations count as seats.",
"codeQuestion": "Can Hub run code on my machines?",
"codeAnswer": "Only on daemons where you grant the <code>hub.execute</code> permission. Enrolling a daemon does not enable execution by default, and you can revoke the permission from the machine at any time.",
"moveQuestion": "Do I have to move my team to a new tool?",
"moveAnswer": "No. The Hub works in the Slack or Discord your team already uses, and on the daemons you already run. When the work gets serious you switch to the Paseo app on those same daemons.",
"moveAnswer": "No. Hub runs from GitHub, Linear, Slack, Discord, schedules, and webhooks on the daemons you already use. When you want to inspect or steer a run directly, open the live session in Paseo on desktop or mobile.",
"agentsQuestion": "Which agents does it run?",
"agentsAnswer": "Whichever ones your daemons have configured, with your own subscriptions and skills. The Hub ships no agent of its own.",
"codeQuestion": "Can the Hub run code on my machines?",
"codeAnswer": "Yes, on the daemons you connect to it and nowhere else. That is the whole point of triggers, and it's why access to the beta stays small and trusted.",
"accessQuestion": "How do I get access?",
"accessAnswer": "You can self-host today or <hosted>sign in to Hosted Hub</hosted> for a free account. When you want more agent runs or more seats, upgrade from Billing inside Hub."
"agentsAnswer": "Hub runs the providers configured on your connected Paseo daemons, including custom providers from plugins. Agents use the subscriptions, models, and skills on those machines.",
"plannedQuestion": "What else is planned?",
"plannedIntro": "These capabilities are not built yet, and are listed so you know where Hub is heading.",
"plannedProvisioning": "Provisioning remote daemons for your team",
"plannedSharing": "Sharing settings and skills across a team",
"plannedIntegrations": "Additional provider integrations",
"accessQuestion": "How do I get started?",
"accessAnswer": "Self-host Hub with <code>npx @getpaseo/hub</code> or <hosted>sign in to hosted Hub</hosted> with a free account. Upgrade from Billing inside Hub when you need more runs or seats."
}
},
"changelog": {
+245 -72
View File
@@ -348,6 +348,20 @@
"intro": "Paseo 原生支持许多 Agent,还可以运行任何 <acp>ACP Agent</acp>,你也可以通过<plugins>插件</plugins>添加新的 Provider。"
},
"landing": {
"hubEyebrow": {
"product": "Paseo Hub",
"label": "在你自己的机器上自动化运行"
},
"eyebrows": {
"providers": "Provider",
"plugins": "插件",
"openSource": "开源理念"
},
"closingCta": {
"eyebrow": "开始使用",
"title": "你的 Agent,在每块屏幕上。",
"description": "下载桌面应用,或在任意机器上运行 daemon。基于 Apache 2.0 开源。"
},
"socialProof": {
"title": "深受开发者喜爱",
"description": "看看开发者们怎么评价 Paseo",
@@ -369,9 +383,17 @@
"remoteDescription": "在家庭实验室或云主机上运行 Paseo",
"remoteCta": "文档",
"teamsTitle": "团队与触发器",
"teamsDescription": "共享访问权限,或从 GitHub、Slack 和 Discord 发起工作",
"teamsDescription": "通过 Paseo Hub 与团队共享 daemon 并自动化运行 Agent",
"teamsCta": "Paseo Hub"
},
"hubSection": {
"description": "通过 GitHub、Linear、Slack、Discord、定时任务或 webhook 在你的机器上运行 Agent。",
"flowTriggers": "触发来源",
"flowDaemons": "已连接的 daemon",
"flowOpenSession": "在 Paseo 中打开实时会话",
"exploreCta": "了解 Paseo Hub",
"docsCta": "自托管文档"
},
"automation": {
"title": "为自动化而生",
"description": "使用 MCP、CLI 或 TypeScript SDK 自动化 Paseo",
@@ -393,7 +415,9 @@
"plan": "我会把它做成本地插件并安装。",
"done": "审查队列已出现在你的侧边栏。",
"panelTitle": "审查队列",
"libraryTitle": "400 多个社区插件",
"libraryTitle": "社区插件",
"libraryTitleCount_one": "{{count}} 个社区插件",
"libraryTitleCount_other": "{{count}} 个社区插件",
"libraryDescription": "开发者用的是和你的 Agent 相同的插件 API",
"browse": "浏览插件",
"docs": "插件文档",
@@ -580,25 +604,213 @@
"reddit": "工作流与问答。"
},
"hub": {
"metaTitle": "Paseo Hub - GitHub、Slack 和 Discord 触发器",
"metaDescription": "自行运行 Paseo Hub,从 GitHub、Slack 和 Discord 在你自己的机器上启动 Agent。",
"metaTitle": "Paseo Hub - 在你的机器上自动化运行 Agent",
"metaDescription": "通过 GitHub、Linear、Slack、Discord、定时任务和 webhook,在你的 Paseo daemon 上自动运行 Agent。你可以自托管 Hub 或使用托管服务。",
"title": "Paseo Hub",
"intro": "一个可选服务,位于你的 daemon 之上,为它们提供额外能力。",
"runIt": "可以自行运行,也可以使用托管服务。",
"intro": "自动化运行编程 Agent,并与团队共享 daemon。每次运行都在你自己的机器上执行。",
"runIt": "可基于 Apache 2.0 自托管运行,也可以使用托管服务。",
"hero": {
"getStarted": "开始使用",
"selfHost": "自托管"
},
"eyebrows": {
"architecture": "架构",
"pricing": "定价"
},
"automations": {
"title": "来自各类来源的自动化",
"description": "触发器监听你各类工具中的事件,并在已连接的 daemon 上启动 Agent。"
},
"sources": {
"github": {
"name": "GitHub",
"description": "Issue、PR 和评论。"
},
"linear": {
"name": "Linear",
"description": "Issue、分配和评论。"
},
"slack": {
"name": "Slack",
"description": "频道和讨论串中的提及。"
},
"discord": {
"name": "Discord",
"description": "频道和讨论串中的提及。"
},
"schedules": {
"name": "定时任务",
"description": "按你的时区定时运行。"
},
"webhooks": {
"name": "Webhook",
"description": "来自任意服务或脚本的事件。"
}
},
"demo": {
"shared": {
"tablistLabel": "自动化来源预览",
"openInPaseo": "在 Paseo 中打开",
"testsPassed": "测试通过",
"appBadge": "APP",
"docsLink": "阅读 {{source}} 文档"
},
"slack": {
"alt": "#engineering 中的 Slack 讨论串,展示 mo 提及 @paseo-bot 查看 P0 issue 并创建 PR",
"searchPlaceholder": "搜索 Paseo",
"channels": "频道",
"apps": "应用",
"channelTopic": "核心 daemon、移动端与 Hub",
"threadReplies": "3 条回复",
"typing": "paseo-bot 正在输入...",
"composerPlaceholder": "回复...",
"showIssues": "<mention/> 给我看看最新的 P0 issue",
"issuesOpen": "目前有 3 个未关闭的 P0 issue:",
"createPr": "<mention/> 为第一个创建一个 PR",
"ranOn": "已在 <host>macbook-pro</host> 上继续运行。已创建 <pr>getpaseo/paseo#1234</pr>,修复了终端写入问题。",
"filesChanged": "3 个文件已更改",
"caption": "在同一讨论串中回复即可继续引导 Agent,或随时在 Paseo 中打开会话。"
},
"github": {
"alt": "GitHub issue #2811,展示 mo 添加标签后 paseo-bot 创建 PR #2819 并通过全部检查",
"issueTitle": "高负载下终端输出丢帧",
"issueMeta": "于 14 分钟前创建此 issue · 2 条评论",
"authorBadge": "Owner",
"botBadge": "bot",
"openedAgo": "14 分钟前",
"repliedAgo": "9 分钟前",
"issueBody": "PTY 缓冲区写满时,突发输出会丢失帧。<mention/> 复现这个问题并提交修复。",
"addedLabel": "添加了标签",
"startedOn": "paseo-bot 已在 macbook-pro 上启动",
"botReply": "已在 <host>macbook-pro</host> 上通过 64 KB 突发测试复现,并创建 <pr>#2819</pr> 限制并排空写入队列。",
"checksPassed": "全部 4 项检查已通过",
"assignees": "负责人",
"labels": "标签",
"development": "开发关联",
"daemon": "daemon",
"caption": "添加 issue 标签或发表评论,即可在你的 daemon 上启动 Agent 并创建 PR。"
},
"linear": {
"alt": "Linear issue PAS-418 分配给 paseo-bot 后在 devbox 上运行并关联 PR #2822",
"issueTitle": "Android 休眠唤醒后中继陷入重连循环",
"issueDescription": "手机从 Doze 模式唤醒后,中继套接字每 200ms 重试一次且没有退避。",
"activity": "动态",
"assignedEvent": "将此 issue 分配给了",
"runningOn": "已在 <host>devbox</host> 上运行 · Codex",
"traceLine": "已读取 relay/reconnect.ts,添加带抖动的退避和唤醒重置",
"botSummary": "已在 <code>relay/reconnect.ts</code> 中添加指数退避与唤醒状态重置,并补充了回归测试。PR 已准备好等待审查。",
"properties": "属性",
"status": "状态",
"priority": "优先级",
"assignee": "负责人",
"creator": "创建者",
"labels": "标签",
"daemon": "daemon",
"caption": "将 issue 分配给 Agent,即可在你的 daemon 上运行修复并把 PR 关联回来。"
},
"discord": {
"alt": "Discord 频道 #engineering,展示 mo 提及 @paseo-bot 后在讨论串中收到 PR #2825",
"textChannels": "文字频道",
"channelTopic": "daemon 与 CLI 工程",
"threadTitle": "修复残留 worktree",
"time1": "今天 10:12",
"time2": "今天 10:16",
"userPrompt": "<mention/> 修复 <issue/> 里残留 worktree 分支未清理的问题",
"startedThread": "发起了讨论串:",
"botStarted": "正在 <host>devbox</host> 上使用 OpenCode 运行,正在检查 worktree 关闭钩子。",
"botFinished": "已在 Agent 工作区关闭时自动清理孤立分支,并添加了测试。",
"fieldHost": "主机",
"fieldDiff": "改动",
"fieldChecks": "检查",
"composerPlaceholder": "发送消息到 #engineering",
"caption": "在频道中提及 @paseo-bot,即可在讨论串里启动 Agent 并回传结果。"
},
"schedules": {
"alt": "每日 CI 优化定时任务在上午 7:00 于 devbox 上运行,创建 PR #2831 并在 Slack 发布摘要",
"active": "运行中",
"jobTitle": "每日 CI 优化",
"cadence": "工作日 7:00 America/New_York",
"step1Title": "定时运行 #42 分析了过去 24 小时的 CI",
"step1Detail": "发现 <code>website-e2e</code> 有 18% 的概率不稳定,且冷启动 Rust 构建增加了 2m 40s。",
"step2Title": "已在 devbox 上创建 PR",
"metricRuntime": "平均耗时",
"metricFlake": "e2e 不稳定率",
"metricCache": "Cargo 缓存",
"slackPosted": "已发送到 Slack",
"slackSummary": "早间 CI 报告:将平均 workflow 耗时从 <strong>7m 12s</strong> 降至 <strong>4m 28s</strong>,并在 <pr>#2831</pr> 中修复了 e2e 不稳定问题。",
"notifiedMo": "抄送 @mo",
"caption": "按你的时区定时运行 Agent,自动创建 PR 并将摘要发送到 Slack。"
},
"webhooks": {
"alt": "终端发送 webhook POST 请求。Hub 返回 202 Accepted 并在 devbox 上启动 Codex 运行。",
"runMeta": "devbox · Codex · getpaseo/paseo",
"statusDone": "已创建 PR",
"trace1": "已在独立 worktree 中检出 <code>v0.19.4</code>",
"trace2": "定位到 <code>ECONNRESET</code> 来自 <code>relay/server.ts</code> 的空闲 keepalive 超时",
"trace3": "已创建 <pr/> 并附带修复与回归测试,全部检查已通过",
"triggeredBy": "webhook · sentry-alert",
"routedLine": "Hub 已路由到 devbox · 118ms",
"caption": "从任意脚本或服务发送 POST 请求,即可立即在你的 daemon 上启动 Agent。"
}
},
"authoring": {
"title": "在仪表盘配置,或以代码方式部署",
"description": "在浏览器中设置触发器,或将 YAML 文件提交到仓库并通过 CLI 部署。",
"dashboardTitle": "仪表盘与运行活动",
"dashboardDescription": "在浏览器中选择 daemon 和工作目录。配置触发器时,Hub 会检查该 daemon 提供哪些 Provider、模型和模式。",
"triggersLabel": "触发器:",
"triggersText": "在表单或 YAML 视图中创建、编辑或暂停自动化。",
"validationLabel": "实时校验:",
"validationText": "查看已连接的 daemon 提供的 Provider、模型和模式。",
"activityLabel": "运行活动:",
"activityText": "查看事件投递、路由结果、输出和错误。",
"docsLink": "阅读配置文档"
},
"shape": {
"title": "与团队共享,锁定在你的机器上",
"description": "Hub 连接到你已在运行的 daemon。团队共享触发器与运行历史,你的代码留在你自己的机器上。",
"triggersRow": "自动化来源",
"webhooks": "webhook、提及与定时任务",
"hub": "Hub",
"hubHosting": "自托管或托管",
"sameRpcs": "与应用和 CLI 相同的 RPC",
"daemonsRow": "已连接的 daemon",
"directOrRelay": "直连或端到端加密中继",
"appsRow": "Paseo 客户端",
"desktop": "桌面端",
"web": "网页端",
"mobile": "移动端",
"cli": "CLI"
},
"guardrails": {
"optInTitle": "主动授权执行",
"optInDescription": "每个 daemon 的 <code>hub.execute</code> 权限默认关闭,按机器单独授予。",
"scopedTitle": "受控触发范围",
"scopedDescription": "事件触发器支持发送者白名单和资源过滤。你可以为每个步骤设置 GitHub 权限,也可以限制 Slack 和 Discord 工具的使用范围。",
"visibilityTitle": "团队可见性",
"visibilityDescription": "所有者、管理员和成员共享 daemon、触发器、运行历史和路由结果。"
},
"agents": {
"title": "运行你已有的 Agent",
"description": "Hub 会发现每个已连接的 Paseo daemon 上的 Provider。你可以运行 Claude Code、Codex、OpenCode、Pi 和自定义 Provider,包括插件提供的 Provider。"
},
"pricing": {
"title": "选择 Hub 的运行方式",
"unavailable": "方案对比暂时不可用。",
"selfHost": "自托管 Hub",
"title": "自托管或托管",
"seatNote": "你可以按 Apache 2.0 许可自行运行开源 Hub,或使用托管服务。Hub 仪表盘成员和待接受的邀请都计入席位。",
"unavailable": "托管方案对比暂时不可用。",
"selfHost": "自托管文档",
"selfHosted": "自托管",
"free": "免费",
"openSource": "/ 开源",
"openSource": "/ Apache 2.0",
"getStarted": "开始使用",
"operateHub": "由你运营 Hub",
"operateHub": "通过 <code>npx @getpaseo/hub</code> 或 Docker Compose 运行",
"allSources": "GitHub、Linear、Slack、Discord、定时任务与 webhook",
"managedSources": "GitHub、Linear、Slack、Discord、定时任务与 webhook",
"ownApps": "由你创建和控制的 Provider 应用",
"openSourceFeature": "开源",
"openSourceFeature": "Apache 2.0 开源",
"unlimitedRuns": "无限次 Agent 运行",
"runsPerMonth": "每月 {{value}} 次 Agent 运行",
"unlimitedUnits": "无限{{unit}}",
"noSeatCap": "无席位上限",
"units_one": "{{value}} 个{{unit}}",
"units_other": "{{value}} 个{{unit}}",
"perMonth": "/ 月",
@@ -607,71 +819,32 @@
"perUnitMonths": "每{{unit}} / {{count}} 个月",
"seat": "席位"
},
"triggers": {
"title": "触发器,运行在你的机器上",
"description": "在 GitHub、Slack 或 Discord 中提及机器人,就会在你的 daemon 上启动一个 Agent。",
"github": "Issue、PR 和代码审查。",
"slack": "频道和讨论串。",
"discord": "频道和讨论串。"
},
"demo": {
"showIssues": "<mention/> 给我看看最新的 P0 issue",
"issuesOpen": "目前有三个未关闭的 P0 issue:",
"createPr": "<mention/> 为第一个创建一个拉取请求",
"ranOn": "已在 <host>macbook-pro</host> 上运行。已创建 <pr>getpaseo/paseo#1234</pr>,修复了终端写入问题。",
"filesChanged": "3 个文件已更改",
"testsPassed": "测试通过",
"bot": "机器人",
"caption": "Agent 在你的 daemon 上运行,使用你的密钥。"
},
"agents": {
"title": "运行你已有的 Agent",
"description": "Hub 本身不附带任何 Agent,因此你的团队使用的是 daemon 上已配置好的 Provider、订阅和技能。"
},
"shape": {
"title": "适配你现有的基础设施",
"description": "Hub 连接到你已在运行的 daemon,你的应用也继续连接这些 daemon。",
"triggersRow": "触发器和团队成员",
"yourTeam": "你的团队",
"futureIntegrations": "未来的集成",
"webhooks": "webhook 和提及",
"hub": "Hub",
"hubHosting": "自托管或托管",
"sameRpcs": "与应用和 CLI 相同的 RPC",
"daemonsRow": "你的 daemon",
"directOrRelay": "直连或中继",
"appsRow": "Paseo 应用",
"desktop": "桌面端",
"web": "网页端",
"mobile": "移动端",
"cli": "CLI"
},
"faq": {
"title": "常见问题",
"whatQuestion": "Hub 是什么?",
"whatAnswer": "一个独立的服务,位于你的 Paseo daemon 之上。你把一个或多个 daemon 连接到它,它就为这些 daemon 提供 GitHub、Slack 和 Discord 触发器,协作功能也在计划中。没有它,Paseo 也能完整工作。",
"separateQuestion": "为什么它是独立服务,而不是 daemon 的一部分?",
"separateAnswer1": "daemon 保持为单台机器上的一个精简可执行程序。Hub 通过与应用和 CLI 相同的 RPC 与 daemon 通信,所以任何人都可以基于 Paseo 构建自己的 hub。",
"separateAnswer2": "它的职责也不同。Hub 需要暴露在互联网上、与团队共享,并以多租户方式运行。这些都不属于单机 daemon 的职责。",
"whatQuestion": "Paseo Hub 是什么?",
"whatAnswer": "Paseo Hub 是位于你的 Paseo daemon 之上的独立服务。连接一个或多个 daemon 后,可以通过 GitHub、Linear、Slack、Discord、定时任务和 webhook 自动化运行 Agent,并与团队共享。没有 Hub,Paseo 也能独立工作。",
"separateQuestion": "为什么 Hub 是独立服务,而不是 daemon 的一部分?",
"separateAnswer1": "daemon 保持为单台机器上的单一进程。Hub 通过与应用和 CLI 相同的 RPC 与 daemon 通信,所以任何人都可以基于 Paseo 构建自己的服务。",
"separateAnswer2": "Hub 的职责也不同。它接收公网 webhook、管理团队访问并以多租户方式运行,这些都不属于单机 daemon。",
"selfHostQuestion": "我可以自己运行吗?",
"selfHostAnswer": "可以。运行 <code>npx @getpaseo/hub</code>,然后在浏览器中完成设置。源代码在 <github>GitHub</github> 上,更复杂的部署请参阅<guide>自托管指南</guide>。",
"selfHostAnswer": "可以。运行 <code>npx @getpaseo/hub</code> 或使用 Docker Compose 启动,然后在浏览器中完成设置。Apache 2.0 源代码在 <github>GitHub</github> 上,生产部署请参阅<guide>自托管指南</guide>。",
"needQuestion": "运行它需要什么?",
"needAnswer": "Node.js 和一个正在运行的 Paseo daemon。Hub 会引导你连接需要的 Provider 应用。",
"needAnswer": "需要 Node.js 或 Docker,以及一个正在运行的 Paseo daemon。Hub 会引导你连接 daemon 和 Provider 应用。",
"hostedQuestion": "有托管版本吗?",
"hostedAnswer": "有。托管服务运行的就是你可以自托管的同一套 Hub 软件。",
"plannedQuestion": "还计划了什么?",
"plannedIntro": "以下尚未实现,列出来是为了让你了解方向。",
"plannedProvisioning": "为团队预配 daemon",
"plannedSharing": "在团队内共享设置和技能",
"plannedIntegrations": "更多集成",
"moveQuestion": "我需要把团队迁移到新工具吗?",
"moveAnswer": "不需要。Hub 在你团队已在使用的 Slack 或 Discord 中工作,运行在你已有的 daemon 上。工作变得复杂时,你可以在同样的 daemon 上切换到 Paseo 应用。",
"agentsQuestion": "它运行哪些 Agent?",
"agentsAnswer": "你的 daemon 上配置了哪些就运行哪些,使用你自己的订阅和技能。Hub 本身不附带任何 Agent。",
"hostedAnswer": "有。<hosted>托管服务</hosted>运行的就是你可以自托管的同一套开源 Hub 软件。Hub 仪表盘成员和待接受的邀请都计入席位。",
"codeQuestion": "Hub 能在我的机器上运行代码吗?",
"codeAnswer": "能,但仅限于你连接到它的 daemon,其他地方都不行。这正是触发器的意义,也是测试版访问范围保持小而可信的原因。",
"accessQuestion": "如何获得访问权限?",
"accessAnswer": "你现在就可以自托管,或<hosted>登录托管版 Hub</hosted> 获取免费账户。需要更多 Agent 运行次数或更多席位时,可在 Hub 内的账单页面升级。"
"codeAnswer": "只能在授予了 <code>hub.execute</code> 权限的 daemon 上运行。注册 daemon 默认不会开启执行权限,你可以随时在本机撤销该权限。",
"moveQuestion": "我需要把团队迁移到新工具吗?",
"moveAnswer": "不需要。Hub 通过 GitHub、Linear、Slack、Discord、定时任务和 webhook 在你已有的 daemon 上运行。需要直接查看或引导运行时,在桌面端或移动端的 Paseo 中打开实时会话即可。",
"agentsQuestion": "它运行哪些 Agent?",
"agentsAnswer": "Hub 运行已连接的 Paseo daemon 上配置的 Provider,包括插件提供的自定义 Provider。Agent 使用这些机器上的订阅、模型和技能。",
"plannedQuestion": "还计划了什么?",
"plannedIntro": "以下能力尚未实现,列出来是为了让你了解 Hub 的方向。",
"plannedProvisioning": "为团队预配远程 daemon",
"plannedSharing": "在团队内共享设置和技能",
"plannedIntegrations": "更多 Provider 集成",
"accessQuestion": "如何开始使用?",
"accessAnswer": "运行 <code>npx @getpaseo/hub</code> 自托管 Hub,或<hosted>登录托管版 Hub</hosted> 获取免费账户。需要更多运行次数或席位时,可在 Hub 内的账单页面升级。"
}
},
"changelog": {
+2 -2
View File
@@ -50,7 +50,7 @@ Distribution: native apps for Mac, Windows, Linux, iOS, and Android; web app; Ho
path: "/hub",
title: "Paseo Hub",
description:
"Connect daemons and run GitHub, Slack, Discord, and Linear workflows through the hosted service or your own deployment.",
"Connect daemons and automate agents from GitHub, Linear, Slack, Discord, schedules, and webhooks through the hosted service or your own deployment.",
},
{
path: "/blog",
@@ -104,7 +104,7 @@ Paseo 支持 Claude Code、Codex、GitHub Copilot、OpenCode、Pi、Antigravity
path: "/hub",
title: "Paseo Hub",
description:
"连接 daemon,通过托管服务或你自己的部署运行 GitHub、Slack、Discord 和 Linear 工作流。",
"连接 daemon,通过托管服务或你自己的部署,使用 GitHub、Linear、Slack、Discord、定时任务和 webhook 自动化运行 Agent。",
},
{ path: "/blog", title: "博客", description: "Paseo 团队的动态和技术文章。" },
{ path: "/privacy", title: "隐私", description: "隐私政策。" },
+1 -1
View File
@@ -1,2 +1,2 @@
export * from "./registry";
export { getRegistry, getRegistryPlugin } from "./loader";
export { getPluginCount, getRegistry, getRegistryPlugin } from "./loader";
+6
View File
@@ -3,6 +3,7 @@ import { env } from "cloudflare:workers";
import { getWebsiteCacheContext } from "~/cloudflare-cache";
import {
loadInstallCounts,
loadPluginCount,
loadRegistryIndex,
loadRegistryPlugin,
type RegistryEnvironment,
@@ -28,3 +29,8 @@ export const getRegistry = createServerFn({ method: "GET" }).handler(async () =>
export const getRegistryPlugin = createServerFn({ method: "GET" })
.validator((id: string) => id)
.handler(({ data }) => loadRegistryPlugin(registryBase(), data, getWebsiteCacheContext()));
/** Listed plugin count from the cached registry index. */
export const getPluginCount = createServerFn({ method: "GET" }).handler(() =>
loadPluginCount(registryBase(), getWebsiteCacheContext()),
);
@@ -13,6 +13,7 @@ import {
useState,
} from "react";
import { useTranslation } from "react-i18next";
import { MOBILE_PAGE_BLEED_CLASS } from "~/components/page-frame";
const TILE_CLASS =
"relative block aspect-video w-[85%] flex-shrink-0 overflow-hidden rounded-xl border border-white/10 bg-white/[0.03] sm:w-[60%]";
@@ -80,7 +81,9 @@ export function MediaGallery({ name, media }: { name: string; media: string[] })
const tileClass = items.length > 2 ? PEEKING_TILE_CLASS : FILLING_TILE_CLASS;
return (
<>
<div className="-mx-6 mt-10 flex gap-3 overflow-x-auto px-6 md:mx-0 md:px-0">
<div
className={`${MOBILE_PAGE_BLEED_CLASS} mt-10 flex gap-3 overflow-x-auto sm:-mx-8 sm:px-8 md:mx-0 md:px-0`}
>
{entries.map((entry) =>
typeof entry === "string" ? (
<p key={entry}>{entry}</p>
+24 -5
View File
@@ -5,7 +5,11 @@ import {
} from "@getpaseo/protocol/plugin-registry";
import { languageAlternates, LOCALES, localizePath } from "~/i18n";
import { SITE_ORIGIN } from "~/meta";
import { getBlockingColdCache, type WebsiteCacheContext } from "../github-cache";
import {
getBlockingColdCache,
getNonBlockingColdCache,
type WebsiteCacheContext,
} from "../github-cache";
import { handlePluginThumbnailRequest } from "./thumbnails";
import { CATEGORIES } from "./categories";
import { type InstallCounts, readInstallCounts, recordClientInstall } from "./installs";
@@ -19,14 +23,29 @@ async function documentAt(base: string, path: string): Promise<unknown> {
if (!response.ok) throw new Error(`Plugin registry returned ${response.status}`);
return response.json();
}
export function loadRegistryIndex(base: string, context: WebsiteCacheContext) {
return getBlockingColdCache({
function registryIndexCache(base: string, context: WebsiteCacheContext) {
return {
context,
key: `plugins:index:v1:${base}`,
isValue: (value): value is ReturnType<typeof PluginRegistryIndexSchema.parse> =>
isValue: (value: unknown): value is ReturnType<typeof PluginRegistryIndexSchema.parse> =>
PluginRegistryIndexSchema.safeParse(value).success,
fetchFresh: async () => PluginRegistryIndexSchema.parse(await documentAt(base, "index.json")),
});
};
}
export function loadRegistryIndex(base: string, context: WebsiteCacheContext) {
return getBlockingColdCache(registryIndexCache(base, context));
}
/** Count of listed plugins from the cached registry index. */
export async function loadPluginCount(
base: string,
context: WebsiteCacheContext,
): Promise<number | null> {
try {
const index = await getNonBlockingColdCache(registryIndexCache(base, context));
return index?.plugins.length ?? null;
} catch {
return null;
}
}
/** Install counts per window for every listed plugin, refreshed with the index cache. */
export async function loadInstallCounts(base: string, context: WebsiteCacheContext) {
+64 -2
View File
@@ -1,5 +1,5 @@
import { createHash } from "node:crypto";
import { createServer } from "node:http";
import { createServer, type ServerResponse } from "node:http";
import { describe, expect, it } from "vitest";
import { getTranslator } from "~/i18n";
import {
@@ -19,7 +19,12 @@ import {
updatedAgo,
} from "./registry";
import { readInstallCounts, recordInstall } from "./installs";
import { handlePluginRegistryRequest, loadRegistryIndex, loadRegistryPlugin } from "./published";
import {
handlePluginRegistryRequest,
loadPluginCount,
loadRegistryIndex,
loadRegistryPlugin,
} from "./published";
const plugin: Plugin = {
id: "acme/example",
name: "Example",
@@ -372,6 +377,63 @@ describe("plugin registry", () => {
expect(at("https://gitlab.com/acme/example")).toBeUndefined();
expect(at("javascript:alert(1)")).toBeUndefined();
});
it("reads the listed plugin count from the registry index and falls back to null on errors", async () => {
const context = { cache: seededIndex(), waitUntil: () => undefined };
expect(await loadPluginCount("https://registry.example.test", context)).toBe(1);
const server = createServer((_request, response) => {
response.statusCode = 503;
response.end("unavailable");
});
await new Promise<void>((resolve) => server.listen(0, "127.0.0.1", resolve));
const address = server.address();
if (!address || typeof address === "string") throw new Error("Expected numeric port");
try {
const count = await loadPluginCount(`http://127.0.0.1:${address.port}`, {
cache: memoryKv(),
waitUntil: () => undefined,
});
expect(count).toBeNull();
} finally {
server.close();
}
});
it("returns a cold landing-page count before the registry responds and warms the shared index", async () => {
const index = {
schemaVersion: 1,
registry: { name: "Test", url: "https://registry.example.test" },
categories: [],
plugins: [plugin],
featured: [],
generatedAt: "2026-10-03",
};
const server = createServer();
const requested = new Promise<ServerResponse>((resolve) => {
server.once("request", (_request, response) => resolve(response));
});
await new Promise<void>((resolve) => server.listen(0, "127.0.0.1", resolve));
const address = server.address();
if (!address || typeof address === "string") throw new Error("Expected numeric port");
const base = `http://127.0.0.1:${address.port}`;
const pending: Promise<unknown>[] = [];
const context = {
cache: memoryKv(),
waitUntil: (promise: Promise<unknown>) => pending.push(promise),
};
const count = loadPluginCount(base, context);
try {
expect(await Promise.race([count, requested.then(() => "waiting on registry")])).toBeNull();
const response = await requested;
response.end(JSON.stringify(index));
await Promise.all(pending);
expect(await loadPluginCount(base, context)).toBe(1);
} finally {
server.closeAllConnections();
await new Promise<void>((resolve) => server.close(() => resolve()));
}
});
});
/** A cache holding a fresh registry index with `plugin`, so no request reaches the registry. */
+381 -393
View File
@@ -1,21 +1,23 @@
import { createFileRoute } from "@tanstack/react-router";
import { Check, CircleHelp } from "lucide-react";
import {
ArrowRight,
Check,
CircleHelp,
Filter,
ShieldCheck,
SlidersHorizontal,
Users,
} from "lucide-react";
import * as React from "react";
import type { ReactNode } from "react";
import { Trans, useTranslation } from "react-i18next";
import type { TFunction } from "i18next";
import {
ClaudeCodeIcon,
CodexIcon,
CursorIcon,
OpenCodeIcon,
PiIcon,
} from "~/components/agent-icons";
import { DiscordIcon, GitHubIcon, SlackIcon } from "~/components/brand-icons";
import { HubLockup, PaseoHubLockup, PaseoHubMark } from "~/components/paseo-brand";
import { AGENT_PAGES } from "~/data/agent-pages";
import { FAQItem } from "~/components/faq-item";
import { SiteShell } from "~/components/site-shell";
import { HubAutomationsShowcase } from "~/components/hub-automations";
import { HUB_AGENT_HARNESSES, HubArchitectureDiagram } from "~/components/hub-flow";
import { ChapterBand, HairlineGrid, PageHeaderBand, SectionOpener } from "~/components/page-frame";
import { PaseoHubLockup } from "~/components/paseo-brand";
import { SiteFooter } from "~/components/site-footer";
import {
billingUnitLabel,
formatPlanPrice,
@@ -58,68 +60,340 @@ export const Route = createFileRoute("/{-$locale}/hub")({
const HOSTED_HUB_URL = "https://hub.paseo.sh";
const LINK_CLASS = "underline hover:text-white/80";
const PRIMARY_CTA_CLASS =
"inline-flex items-center justify-center gap-2 rounded-lg bg-foreground px-4 py-2.5 text-sm font-medium text-background transition-colors hover:bg-foreground/90";
const SECONDARY_CTA_CLASS =
"inline-flex items-center justify-center gap-2 rounded-lg border border-white/12 px-4 py-2.5 text-sm text-white/85 transition-colors hover:bg-white/10 hover:text-white";
function Hub() {
const { t } = useTranslation();
const { plans } = Route.useLoaderData();
return (
<SiteShell width="default">
<h1 className="mb-5">
<PaseoHubLockup className="h-9 md:h-10 w-auto text-foreground" />
<div className="min-h-screen bg-background">
<PageHeaderBand />
<main>
<ChapterBand spacing="hero" ruled={false} ticks={false} framed={false}>
<HubHero />
</ChapterBand>
<ChapterBand spacing="section">
<AutomationsSection />
</ChapterBand>
<ChapterBand spacing="section">
<AuthoringSection />
</ChapterBand>
<ChapterBand spacing="section">
<InfrastructureSection />
</ChapterBand>
<ChapterBand spacing="compact">
<AgentsSection />
</ChapterBand>
<ChapterBand spacing="section" tint="subtle">
<PricingSection plans={plans} />
</ChapterBand>
<ChapterBand spacing="section">
<FaqSection />
</ChapterBand>
</main>
<SiteFooter width="default" />
</div>
);
}
function HubHero() {
const { t } = useTranslation();
const localize = useLocalizePath();
return (
<header className="space-y-6">
<h1>
<PaseoHubLockup size="display" className="h-10 w-auto text-foreground md:h-12" />
<span className="sr-only">{t("hub.title")}</span>
</h1>
<p className="text-lg text-white/70 leading-relaxed max-w-2xl">{t("hub.intro")}</p>
<p className="text-white/40 text-sm mt-3">{t("hub.runIt")}</p>
<div className="space-y-20 mt-16">
<Triggers />
<Agents />
<Shape />
<Pricing plans={plans} />
<FaqSection />
<p className="max-w-2xl text-lg leading-relaxed text-white/70">{t("hub.intro")}</p>
<div className="flex flex-wrap items-center gap-3 pt-1">
<a href={HOSTED_HUB_URL} className={PRIMARY_CTA_CLASS}>
{t("hub.hero.getStarted")}
<ArrowRight className="h-4 w-4" aria-hidden="true" />
</a>
<a href={localize("/docs/hub")} className={SECONDARY_CTA_CLASS}>
{t("hub.hero.selfHost")}
</a>
</div>
</SiteShell>
<p className="text-sm text-white/45">{t("hub.runIt")}</p>
</header>
);
}
function AutomationsSection() {
const { t } = useTranslation();
return (
<section aria-labelledby="automations-heading">
<SectionOpener
headingId="automations-heading"
title={t("hub.automations.title")}
description={t("hub.automations.description")}
/>
<HubAutomationsShowcase />
</section>
);
}
const DASHBOARD_ITEMS = ["triggers", "validation", "activity"] as const;
function AuthoringSection() {
const { t } = useTranslation();
const localize = useLocalizePath();
return (
<section aria-labelledby="authoring-heading">
<SectionOpener
headingId="authoring-heading"
title={t("hub.authoring.title")}
description={t("hub.authoring.description")}
/>
<HairlineGrid columns="2">
<AuthoringDashboardCard docsHref={localize("/docs/hub/configuration")} />
<AuthoringYamlCard />
</HairlineGrid>
</section>
);
}
function AuthoringDashboardCard({ docsHref }: { docsHref: string }) {
const { t } = useTranslation();
return (
<div className="flex flex-col justify-between gap-6 bg-background p-6">
<div className="space-y-5">
<div className="flex items-center gap-2.5">
<SlidersHorizontal className="h-4 w-4 text-accent-text" strokeWidth={1.5} />
<h3 className="text-base font-medium text-white/90">
{t("hub.authoring.dashboardTitle")}
</h3>
</div>
<p className="text-sm leading-relaxed text-white/65">
{t("hub.authoring.dashboardDescription")}
</p>
<ul className="space-y-3 border-t border-white/[0.08] pt-4">
{DASHBOARD_ITEMS.map((item) => (
<li key={item} className="flex items-start gap-2.5 text-sm">
<Check aria-hidden="true" className="mt-0.5 size-4 shrink-0 text-accent-text" />
<span className="text-white/75">
<span className="font-medium text-white/90">{t(`hub.authoring.${item}Label`)}</span>{" "}
<span className="text-white/55">{t(`hub.authoring.${item}Text`)}</span>
</span>
</li>
))}
</ul>
</div>
<div>
<a
href={docsHref}
className="inline-flex items-center gap-1.5 text-sm text-white/75 transition-colors hover:text-accent-text"
>
{t("hub.authoring.docsLink")}
<ArrowRight className="h-3.5 w-3.5" aria-hidden="true" />
</a>
</div>
</div>
);
}
function AuthoringYamlCard() {
return (
<div className="flex flex-col bg-[#0c1110]">
<div className="flex items-center justify-between border-b border-white/[0.08] bg-white/[0.02] px-5 py-3">
<span className="font-mono text-xs text-white/70">.paseo/triggers/slack-help.yml</span>
<span className="rounded border border-white/10 px-1.5 py-0.5 font-mono text-[10px] text-white/40">
YAML
</span>
</div>
<pre className="flex-1 overflow-x-auto p-5 font-mono text-[12px] leading-6 text-white/75">
<YamlLine k="name" v="slack-help" />
<YamlKey k="on" />
<YamlKey k="slack.mention" indent={2} />
<YamlLine k="connection" v="acme-slack" indent={4} />
<YamlKey k="filters" indent={4} />
<YamlLine k="from_users" v="[U01234567]" indent={6} />
<YamlKey k="run" />
<YamlKey k="target" indent={2} />
<YamlLine k="daemon" v="devbox" indent={4} />
<YamlLine k="cwd" v="/workspace/app" indent={4} />
<YamlKey k="agent" indent={2} />
<YamlLine k="provider" v="codex" indent={4} />
<YamlLine k="mode" v="full-access" indent={4} />
<YamlLine k="continuation" v="{ mode: conversation }" indent={2} />
<YamlLine k="prompt" v="|" indent={2} />
<span className="block text-emerald-300/80">
{" Answer with hub.reply, then call hub.finish_execution."}
</span>
<span className="block text-emerald-300/80">{" <user-prompt>"}</span>
<span className="block text-emerald-300/80">{" ${{ paseo.prompt }}"}</span>
<span className="block text-emerald-300/80">{" </user-prompt>"}</span>
<YamlKey k="outputs" indent={2} />
<YamlKey k="slack.reply" indent={4} />
<YamlLine k="max" v="1" indent={6} />
<YamlLine k="required" v="true" indent={6} />
</pre>
<div className="space-y-1 border-t border-white/[0.08] bg-white/[0.02] px-5 py-3.5 font-mono text-xs text-white/65">
<div>
<span className="select-none text-white/30">$ </span>
<span className="text-white/90">paseo hub deploy</span>{" "}
<span className="text-sky-300/80">--dry-run</span>
</div>
<div>
<span className="select-none text-white/30">$ </span>
<span className="text-white/90">paseo hub deploy</span>
</div>
</div>
</div>
);
}
function YamlKey({ k, indent = 0 }: { k: string; indent?: number }) {
return (
<span className="block">
{" ".repeat(indent)}
<span className="text-sky-300/80">{k}</span>
<span className="text-white/35">:</span>
</span>
);
}
function YamlLine({ k, v, indent = 0 }: { k: string; v: string; indent?: number }) {
return (
<span className="block">
{" ".repeat(indent)}
<span className="text-sky-300/80">{k}</span>
<span className="text-white/35">: </span>
<span className="text-emerald-300/80">{v}</span>
</span>
);
}
const GUARDRAILS = [
{ key: "optIn", Icon: ShieldCheck },
{ key: "scoped", Icon: Filter },
{ key: "visibility", Icon: Users },
] as const;
const GUARDRAIL_CODE_COMPONENTS = {
code: <code className="font-mono text-xs text-white/80" />,
};
function InfrastructureSection() {
const { t } = useTranslation();
return (
<section aria-labelledby="infrastructure-heading">
<SectionOpener
eyebrow={t("hub.eyebrows.architecture")}
headingId="infrastructure-heading"
title={t("hub.shape.title")}
description={t("hub.shape.description")}
/>
<div className="space-y-6">
<HubArchitectureDiagram />
<HairlineGrid columns="3">
{GUARDRAILS.map(({ key, Icon }) => (
<div key={key} className="space-y-2.5 bg-background p-6">
<div className="flex items-center gap-2.5">
<Icon className="h-4 w-4 shrink-0 text-accent-text" strokeWidth={1.5} />
<h3 className="text-sm font-medium text-white/90">
{t(`hub.guardrails.${key}Title`)}
</h3>
</div>
<p className="text-sm leading-relaxed text-white/60">
<Trans
i18nKey={`hub.guardrails.${key}Description`}
components={GUARDRAIL_CODE_COMPONENTS}
/>
</p>
</div>
))}
</HairlineGrid>
</div>
</section>
);
}
function AgentsSection() {
const { t } = useTranslation();
return (
<section aria-labelledby="agents-heading">
<SectionOpener
headingId="agents-heading"
title={t("hub.agents.title")}
description={t("hub.agents.description")}
/>
<HairlineGrid columns="3">
{HUB_AGENT_HARNESSES.map(({ name, Icon }) => (
<div key={name} className="flex items-center gap-3 bg-background px-5 py-4">
<span className="text-white/80">
<Icon className="h-5 w-5" />
</span>
<span className="text-sm font-medium text-white/90">{name}</span>
</div>
))}
</HairlineGrid>
</section>
);
}
interface PlanFeature {
key: string;
label: string;
label: ReactNode;
tooltip: string | null;
}
const SELF_HOSTED_FEATURES = [
{ key: "operate-hub", labelKey: "operateHub" },
{ key: "own-apps", labelKey: "ownApps" },
{ key: "open-source", labelKey: "openSourceFeature" },
] as const;
const PRICING_CODE_COMPONENTS = {
code: <code className="font-mono text-xs text-white/85" />,
};
function Pricing({ plans }: { plans: HubPlans | null }) {
function PricingSection({ plans }: { plans: HubPlans | null }) {
const { t } = useTranslation();
const locale = useLocale();
const localize = useLocalizePath();
const selfHostedFeatures = React.useMemo(
() =>
SELF_HOSTED_FEATURES.map((feature) => ({
key: feature.key,
label: t(`hub.pricing.${feature.labelKey}`),
const selfHostedFeatures = React.useMemo<readonly PlanFeature[]>(
() => [
{
key: "operate-hub",
label: <Trans i18nKey="hub.pricing.operateHub" components={PRICING_CODE_COMPONENTS} />,
tooltip: null,
})),
},
{
key: "all-sources",
label: t("hub.pricing.allSources"),
tooltip: null,
},
{
key: "own-apps",
label: t("hub.pricing.ownApps"),
tooltip: null,
},
{
key: "open-source",
label: t("hub.pricing.openSourceFeature"),
tooltip: null,
},
],
[t],
);
if (plans === null) {
return (
<section className="space-y-6" aria-labelledby="pricing-heading">
<div className="space-y-2">
<h2 id="pricing-heading" className="text-xl font-medium">
{t("hub.pricing.title")}
</h2>
<p className="max-w-2xl leading-relaxed text-white/70">{t("hub.pricing.unavailable")}</p>
</div>
<a
href={localize("/docs/hub/quickstart")}
className="inline-block rounded-md border border-white/15 px-4 py-2 text-sm font-medium text-white/80 transition-colors hover:border-white/25 hover:text-white"
>
<section aria-labelledby="pricing-heading">
<SectionOpener
eyebrow={t("hub.eyebrows.pricing")}
headingId="pricing-heading"
title={t("hub.pricing.title")}
description={t("hub.pricing.unavailable")}
/>
<a href={localize("/docs/hub/self-hosting")} className={SECONDARY_CTA_CLASS}>
{t("hub.pricing.selfHost")}
</a>
</section>
@@ -127,18 +401,21 @@ function Pricing({ plans }: { plans: HubPlans | null }) {
}
return (
<section className="space-y-6" aria-labelledby="pricing-heading">
<h2 id="pricing-heading" className="text-xl font-medium">
{t("hub.pricing.title")}
</h2>
<div className="grid gap-4 md:grid-cols-3">
<section aria-labelledby="pricing-heading">
<SectionOpener
eyebrow={t("hub.eyebrows.pricing")}
headingId="pricing-heading"
title={t("hub.pricing.title")}
description={t("hub.pricing.seatNote")}
/>
<HairlineGrid columns="3" clipContents={false}>
<PlanCard
name={t("hub.pricing.selfHosted")}
price={t("hub.pricing.free")}
priceQualifier={t("hub.pricing.openSource")}
priceTooltip={null}
features={selfHostedFeatures}
actionHref={localize("/docs/hub/quickstart")}
actionHref={localize("/docs/hub/self-hosting")}
actionLabel={t("hub.pricing.selfHost")}
/>
<PlanCard
@@ -160,14 +437,15 @@ function Pricing({ plans }: { plans: HubPlans | null }) {
actionLabel={t("hub.pricing.getStarted")}
featured
/>
</div>
</HairlineGrid>
</section>
);
}
/**
* The figures the plan includes, ahead of the prose the catalog wrote for it. Hub serves plan
* names, feature labels and tooltips in English, so those show as the catalog wrote them.
* names, feature labels and tooltips in English, so those show as the catalog wrote them, except
* the trigger summary key which maps to the current source list on this site.
*/
function planFeatures(plan: HubPlanOffer, t: TFunction, locale: Locale): readonly PlanFeature[] {
return [
@@ -181,7 +459,10 @@ function planFeatures(plan: HubPlanOffer, t: TFunction, locale: Locale): readonl
label: formatSeats(plan.included.seats, billingUnitLabel(plan, t), t, locale),
tooltip: null,
},
...plan.features,
...plan.features.map((feature) => ({
...feature,
label: feature.key === "managed-triggers" ? t("hub.pricing.managedSources") : feature.label,
})),
];
}
@@ -194,7 +475,7 @@ function formatAllowance(executionsPerMonth: number | null, t: TFunction, locale
}
function formatSeats(seats: number | null, unit: string, t: TFunction, locale: Locale): string {
if (seats === null) return t("hub.pricing.unlimitedUnits", { unit });
if (seats === null) return t("hub.pricing.noSeatCap");
return t("hub.pricing.units", { count: seats, value: formatNumber(seats, locale), unit });
}
@@ -219,30 +500,34 @@ function PlanCard({
}) {
return (
<article
className={`flex flex-col rounded-2xl border p-6 ${featured ? "border-white/25 bg-white/[0.06]" : "border-white/10 bg-white/[0.02]"}`}
className={`flex flex-col p-6 first:rounded-t-[inherit] last:rounded-b-[inherit] md:p-7 md:first:rounded-tr-none md:first:rounded-bl-[inherit] md:last:rounded-tr-[inherit] md:last:rounded-bl-none ${featured ? "bg-brand-green/[0.08]" : "bg-background"}`}
>
<h3 className="text-xl font-medium">{name}</h3>
<div className="mt-6 flex items-end gap-2">
<h3 className="text-lg font-medium text-white/90">{name}</h3>
<div className="relative mt-5 flex items-end gap-2">
<span className="text-4xl font-medium tracking-tight">{price}</span>
<span className="mb-1 inline-flex items-center gap-1 text-sm text-white/45">
{priceQualifier}
{priceTooltip !== null && <InfoTip text={priceTooltip} />}
{priceTooltip !== null ? <InfoTip text={priceTooltip} /> : null}
</span>
</div>
{features.length > 0 && (
{features.length > 0 ? (
<ul className="mt-6 grid flex-1 content-start gap-3 text-sm text-white/70">
{features.map((feature) => (
<li key={feature.key} className="flex items-start gap-2.5">
<Check aria-hidden="true" className="mt-0.5 size-4 shrink-0 text-emerald-300" />
<li key={feature.key} className="relative flex items-start gap-2.5">
<Check aria-hidden="true" className="mt-0.5 size-4 shrink-0 text-accent-text" />
<span>{feature.label}</span>
{feature.tooltip !== null && <InfoTip text={feature.tooltip} />}
{feature.tooltip !== null ? <InfoTip text={feature.tooltip} /> : null}
</li>
))}
</ul>
)}
) : null}
<a
href={actionHref}
className={`rounded-md px-4 py-2 text-center text-sm font-medium transition-colors mt-8 ${featured ? "bg-white text-black hover:bg-white/90" : "border border-white/15 text-white/80 hover:border-white/25 hover:text-white"}`}
className={`mt-8 rounded-lg px-4 py-2.5 text-center text-sm font-medium transition-colors ${
featured
? "bg-foreground text-background hover:bg-foreground/90"
: "border border-white/15 text-white/85 hover:border-white/25 hover:bg-white/[0.04] hover:text-white"
}`}
>
{actionLabel}
</a>
@@ -252,11 +537,11 @@ function PlanCard({
function InfoTip({ text }: { text: string }) {
return (
<span className="group relative inline-flex shrink-0" tabIndex={0}>
<span className="group inline-flex shrink-0" tabIndex={0}>
<CircleHelp aria-label={text} className="size-3.5 text-white/35" />
<span
role="tooltip"
className="pointer-events-none absolute bottom-full left-1/2 z-10 mb-2 hidden w-56 -translate-x-1/2 rounded-md border border-white/10 bg-[#17201f] px-3 py-2 text-xs leading-relaxed text-white/75 shadow-xl group-hover:block group-focus:block"
className="pointer-events-none absolute bottom-full left-0 z-10 mb-2 hidden w-full max-w-56 rounded-md border border-white/10 bg-[#17201f] px-3 py-2 text-xs leading-relaxed text-white/75 shadow-xl group-hover:block group-focus:block"
>
{text}
</span>
@@ -264,325 +549,15 @@ function InfoTip({ text }: { text: string }) {
);
}
const TRIGGER_SURFACES = [
{ name: "GitHub", icon: <GitHubIcon className="h-6 w-6" />, body: "github" },
{ name: "Slack", icon: <SlackIcon className="h-6 w-6" />, body: "slack" },
{ name: "Discord", icon: <DiscordIcon className="h-6 w-6" />, body: "discord" },
] as const;
function Triggers() {
const { t } = useTranslation();
return (
<section className="space-y-6">
<h2 className="text-xl font-medium">{t("hub.triggers.title")}</h2>
<p className="text-white/70 leading-relaxed max-w-2xl">{t("hub.triggers.description")}</p>
<div className="grid grid-cols-1 sm:grid-cols-3 gap-4">
{TRIGGER_SURFACES.map((surface) => (
<div
key={surface.name}
className="flex items-center gap-3 rounded-xl border border-white/10 bg-white/[0.03] px-5 py-4"
>
<span className="text-white/80">{surface.icon}</span>
<span className="min-w-0">
<span className="block font-medium">{surface.name}</span>
<span className="block text-xs text-muted-foreground">
{t(`hub.triggers.${surface.body}`)}
</span>
</span>
</div>
))}
</div>
<DiscordDemo />
</section>
);
}
const DEMO_ISSUES = [
{ id: "#2811", title: "Terminal output drops under load" },
{ id: "#2804", title: "Relay reconnect loop on Android after sleep" },
{ id: "#2799", title: "Worktree cleanup leaves stale branches" },
];
const DEMO_COMPONENTS = {
mention: <Mention />,
host: <span className="font-mono text-white/50" />,
pr: <span className="text-white/80 underline decoration-white/20" />,
};
function DiscordDemo() {
const { t } = useTranslation();
return (
<figure className="space-y-3">
<div className="overflow-hidden rounded-2xl border border-white/10 bg-white/[0.02]">
<div className="flex items-center gap-2 border-b border-white/10 bg-white/[0.03] px-5 py-3">
<DiscordIcon className="h-4 w-4 text-white/40" />
<span className="font-mono text-xs text-white/50">#engineering</span>
</div>
<div className="space-y-5 p-5">
<DemoMessage author="moboudra" time="09:41">
<p>
<Trans i18nKey="hub.demo.showIssues" components={DEMO_COMPONENTS} />
</p>
</DemoMessage>
<DemoMessage author="paseo-bot" time="09:41" bot>
<p>{t("hub.demo.issuesOpen")}</p>
<ul className="space-y-1">
{DEMO_ISSUES.map((issue) => (
<li key={issue.id} className="flex gap-2">
<span className="font-mono text-white/40">{issue.id}</span>
<span>{issue.title}</span>
</li>
))}
</ul>
</DemoMessage>
<DemoMessage author="moboudra" time="09:43">
<p>
<Trans i18nKey="hub.demo.createPr" components={DEMO_COMPONENTS} />
</p>
</DemoMessage>
<DemoMessage author="paseo-bot" time="09:48" bot>
<p>
<Trans i18nKey="hub.demo.ranOn" components={DEMO_COMPONENTS} />
</p>
<div className="flex flex-wrap items-center gap-2 pt-1">
<span className="rounded-full bg-emerald-400/10 px-2 py-1 text-xs text-emerald-300">
{t("hub.demo.filesChanged")}
</span>
<span className="rounded-full border border-white/10 px-2 py-1 text-xs text-white/40">
{t("hub.demo.testsPassed")}
</span>
</div>
</DemoMessage>
</div>
</div>
<figcaption className="text-sm text-muted-foreground">{t("hub.demo.caption")}</figcaption>
</figure>
);
}
function Mention() {
return <span className="rounded bg-indigo-400/15 px-1 py-0.5 text-indigo-200">@paseo-bot</span>;
}
function DemoMessage({
author,
time,
bot,
children,
}: {
author: string;
time: string;
bot?: boolean;
children: ReactNode;
}) {
const { t } = useTranslation();
return (
<div className="flex gap-3">
<div className="flex h-8 w-8 flex-shrink-0 items-center justify-center rounded-full border border-white/10 bg-white/[0.06]">
{bot ? (
<PaseoHubMark className="h-5 w-5 text-white" />
) : (
<span className="text-xs font-medium text-white/60">M</span>
)}
</div>
<div className="min-w-0 space-y-1">
<div className="flex items-center gap-2">
<span className="text-sm font-medium text-white/90">{author}</span>
{bot && (
<span className="rounded bg-indigo-400/15 px-1.5 py-0.5 text-[10px] font-medium uppercase tracking-wide text-indigo-200">
{t("hub.demo.bot")}
</span>
)}
<span className="text-xs text-white/25">{time}</span>
</div>
<div className="space-y-2 text-sm text-white/70 leading-relaxed">{children}</div>
</div>
</div>
);
}
const AGENT_LOGOS = [
{ name: "Claude Code", icon: <ClaudeCodeIcon className="h-6 w-6" /> },
{ name: "Codex", icon: <CodexIcon className="h-6 w-6" /> },
{ name: "OpenCode", icon: <OpenCodeIcon className="h-6 w-6" /> },
{ name: "Cursor", icon: <CursorIcon className="h-6 w-6" /> },
{ name: "Pi", icon: <PiIcon className="h-6 w-6" /> },
];
const MORE_AGENT_COUNT = AGENT_PAGES.length - AGENT_LOGOS.length;
function Agents() {
const { t } = useTranslation();
const localize = useLocalizePath();
return (
<section className="space-y-6">
<h2 className="text-xl font-medium">{t("hub.agents.title")}</h2>
<p className="text-white/70 leading-relaxed max-w-2xl">{t("hub.agents.description")}</p>
<div className="flex flex-wrap items-center gap-3">
{AGENT_LOGOS.map((agent) => (
<div
key={agent.name}
className="flex items-center gap-2.5 rounded-xl border border-white/10 bg-white/[0.03] px-4 py-3"
>
<span className="text-white/80">{agent.icon}</span>
<span className="text-sm font-medium">{agent.name}</span>
</div>
))}
<a
href={localize("/agents")}
className="rounded-xl border border-dashed border-white/10 bg-white/[0.01] px-4 py-3 text-sm font-medium text-white/50 hover:text-white/80 hover:border-white/20 transition-colors"
>
{t("common.more", { count: MORE_AGENT_COUNT })}
</a>
</div>
</section>
);
}
const DIAGRAM_SURFACES = [
{ name: "GitHub", icon: <GitHubIcon className="h-5 w-5" /> },
{ name: "Slack", icon: <SlackIcon className="h-5 w-5" /> },
{ name: "Discord", icon: <DiscordIcon className="h-5 w-5" /> },
];
const CLAUDE_MARK = { name: "Claude Code", icon: <ClaudeCodeIcon className="h-4 w-4" /> };
const CODEX_MARK = { name: "Codex", icon: <CodexIcon className="h-4 w-4" /> };
const OPENCODE_MARK = { name: "OpenCode", icon: <OpenCodeIcon className="h-4 w-4" /> };
const PI_MARK = { name: "Pi", icon: <PiIcon className="h-4 w-4" /> };
const DIAGRAM_DAEMONS = [
{ name: "MacBook Pro", agents: [CLAUDE_MARK, CODEX_MARK, OPENCODE_MARK] },
{ name: "Hetzner VM", agents: [CLAUDE_MARK, PI_MARK] },
];
const DIAGRAM_CLIENTS = ["desktop", "web", "mobile", "cli"] as const;
function Shape() {
const { t } = useTranslation();
return (
<section className="space-y-6">
<h2 className="text-xl font-medium">{t("hub.shape.title")}</h2>
<p className="text-white/70 leading-relaxed max-w-2xl">{t("hub.shape.description")}</p>
<div className="rounded-2xl border border-white/10 bg-white/[0.02] p-6 md:p-8">
<div className="flex flex-col items-center">
<DiagramRow label={t("hub.shape.triggersRow")}>
{DIAGRAM_SURFACES.map((surface) => (
<DiagramCard key={surface.name} icon={surface.icon} name={surface.name} />
))}
<DiagramCard name={t("hub.shape.yourTeam")} />
<div className="flex items-center justify-center rounded-xl border border-dashed border-white/10 bg-white/[0.01] px-4 py-3 text-sm text-white/30">
{t("hub.shape.futureIntegrations")}
</div>
</DiagramRow>
<Connector label={t("hub.shape.webhooks")} />
<div className="w-full max-w-xs rounded-xl border border-white/20 bg-white/[0.06] px-6 py-5 text-center">
<p className="flex justify-center">
<HubLockup className="h-[22px] w-auto text-foreground" />
<span className="sr-only">{t("hub.shape.hub")}</span>
</p>
<p className="text-xs text-muted-foreground mt-1.5">{t("hub.shape.hubHosting")}</p>
</div>
<Connector label={t("hub.shape.sameRpcs")} />
<DiagramRow label={t("hub.shape.daemonsRow")}>
{DIAGRAM_DAEMONS.map((daemon) => (
<div
key={daemon.name}
className="flex items-center gap-3 rounded-xl border border-white/10 bg-white/[0.03] px-4 py-3"
>
<span className="text-white/70">
<MachineIcon />
</span>
<span className="text-sm font-medium">{daemon.name}</span>
<span className="flex items-center gap-2 border-l border-white/10 pl-3 text-white/40">
{daemon.agents.map((agent) => (
<span key={agent.name} title={agent.name}>
{agent.icon}
</span>
))}
</span>
</div>
))}
</DiagramRow>
<Connector label={t("hub.shape.directOrRelay")} />
<DiagramRow label={t("hub.shape.appsRow")}>
{DIAGRAM_CLIENTS.map((client) => (
<DiagramCard key={client} name={t(`hub.shape.${client}`)} />
))}
</DiagramRow>
</div>
</div>
</section>
);
}
function DiagramRow({ label, children }: { label: string; children: ReactNode }) {
return (
<div className="w-full space-y-2">
<p className="text-center text-xs uppercase tracking-wide text-white/25">{label}</p>
<div className="flex flex-wrap justify-center gap-3">{children}</div>
</div>
);
}
function DiagramCard({ name, icon }: { name: string; icon?: ReactNode }) {
return (
<div className="flex items-center gap-2.5 rounded-xl border border-white/10 bg-white/[0.03] px-4 py-3">
{icon && <span className="text-white/70">{icon}</span>}
<span className="text-sm font-medium">{name}</span>
</div>
);
}
function Connector({ label }: { label: string }) {
return (
<div className="flex flex-col items-center gap-2 py-4">
<div className="h-5 w-px border-l border-dashed border-white/25" />
<p className="text-center text-[11px] text-white/30">{label}</p>
<div className="h-5 w-px border-l border-dashed border-white/25" />
</div>
);
}
function MachineIcon() {
return (
<svg
width="20"
height="20"
viewBox="0 0 24 24"
fill="none"
stroke="currentColor"
strokeWidth="1.5"
strokeLinecap="round"
strokeLinejoin="round"
aria-hidden="true"
>
<rect x="2" y="2" width="20" height="8" rx="2" />
<rect x="2" y="14" width="20" height="8" rx="2" />
<circle cx="6" cy="6" r="1" />
<circle cx="6" cy="18" r="1" />
</svg>
);
}
const SIMPLE_FAQ_ENTRIES = ["need", "hosted"] as const;
const LATER_FAQ_ENTRIES = ["move", "agents", "code"] as const;
const SIMPLE_FAQ_ENTRIES = ["need"] as const;
const LATER_FAQ_ENTRIES = ["move", "agents"] as const;
function FaqSection() {
const { t } = useTranslation();
const localize = useLocalizePath();
const links = React.useMemo(
() => ({
code: <code />,
code: <code className="font-mono text-xs text-white/80" />,
github: <a href="https://github.com/getpaseo/hub" className={LINK_CLASS} />,
guide: <a href={localize("/docs/hub/self-hosting")} className={LINK_CLASS} />,
hosted: <a href={HOSTED_HUB_URL} className={LINK_CLASS} />,
@@ -590,9 +565,16 @@ function FaqSection() {
[localize],
);
return (
<section className="space-y-6">
<h2 className="text-3xl font-medium">{t("hub.faq.title")}</h2>
<div className="space-y-6">
<section
aria-labelledby="faq-heading"
className="grid items-start gap-10 lg:grid-cols-[minmax(0,17rem)_minmax(0,1fr)] lg:gap-16"
>
<SectionOpener
headingId="faq-heading"
title={t("hub.faq.title")}
className="mb-0 self-start"
/>
<div className="divide-y divide-white/[0.08] border-y border-white/[0.08]">
<FAQItem question={t("hub.faq.whatQuestion")}>{t("hub.faq.whatAnswer")}</FAQItem>
<FAQItem question={t("hub.faq.separateQuestion")}>
<p>{t("hub.faq.separateAnswer1")}</p>
@@ -606,6 +588,17 @@ function FaqSection() {
{t(`hub.faq.${entry}Answer`)}
</FAQItem>
))}
<FAQItem question={t("hub.faq.hostedQuestion")}>
<Trans i18nKey="hub.faq.hostedAnswer" components={links} />
</FAQItem>
<FAQItem question={t("hub.faq.codeQuestion")}>
<Trans i18nKey="hub.faq.codeAnswer" components={links} />
</FAQItem>
{LATER_FAQ_ENTRIES.map((entry) => (
<FAQItem key={entry} question={t(`hub.faq.${entry}Question`)}>
{t(`hub.faq.${entry}Answer`)}
</FAQItem>
))}
<FAQItem question={t("hub.faq.plannedQuestion")}>
<p>{t("hub.faq.plannedIntro")}</p>
<ul className="list-disc space-y-1 pl-5">
@@ -614,11 +607,6 @@ function FaqSection() {
<li>{t("hub.faq.plannedIntegrations")}</li>
</ul>
</FAQItem>
{LATER_FAQ_ENTRIES.map((entry) => (
<FAQItem key={entry} question={t(`hub.faq.${entry}Question`)}>
{t(`hub.faq.${entry}Answer`)}
</FAQItem>
))}
<FAQItem question={t("hub.faq.accessQuestion")}>
<Trans i18nKey="hub.faq.accessAnswer" components={links} />
</FAQItem>
@@ -3,6 +3,7 @@ import { Trans } from "react-i18next";
import { LandingPage } from "~/components/landing-page";
import { getTranslator, routeLocale } from "~/i18n";
import { pageMeta } from "~/meta";
import { getPluginCount } from "~/plugins";
export const Route = createFileRoute("/{-$locale}/")({
head: ({ params }) => {
@@ -15,6 +16,7 @@ export const Route = createFileRoute("/{-$locale}/")({
locale,
});
},
loader: async () => ({ pluginCount: await getPluginCount() }),
component: Home,
});
@@ -32,5 +34,6 @@ const SUBTITLE = (
);
function Home() {
return <LandingPage title={TITLE} subtitle={SUBTITLE} />;
const { pluginCount } = Route.useLoaderData();
return <LandingPage title={TITLE} subtitle={SUBTITLE} pluginCount={pluginCount} showHubEyebrow />;
}
@@ -14,6 +14,7 @@ import {
} from "lucide-react";
import { useMemo } from "react";
import { useTranslation } from "react-i18next";
import { MOBILE_PAGE_BLEED_CLASS } from "~/components/page-frame";
import { SiteShell } from "~/components/site-shell";
import { getTranslator, localizePath, routeLocale, useLocalizePath } from "~/i18n";
import { pageMeta } from "~/meta";
@@ -66,8 +67,7 @@ const CATEGORY_ICONS: Record<CategorySlug, LucideIcon> = {
};
// Card sections: a swipeable row on phones, a grid from `sm` up.
const CARD_ROW_CLASS =
"-mx-6 flex gap-4 overflow-x-auto px-6 pb-1 *:w-[70%] *:flex-shrink-0 sm:mx-0 sm:grid sm:grid-cols-2 sm:px-0 sm:*:w-auto lg:grid-cols-4";
const CARD_ROW_CLASS = `${MOBILE_PAGE_BLEED_CLASS} flex gap-4 overflow-x-auto pb-1 *:w-[70%] *:flex-shrink-0 sm:mx-0 sm:grid sm:grid-cols-2 sm:px-0 sm:*:w-auto lg:grid-cols-4`;
const SEE_ALL_CLASS =
"inline-flex items-center gap-0.5 text-sm text-muted-foreground transition-colors hover:text-foreground";
+7 -7
View File
@@ -1,5 +1,6 @@
@import "tailwindcss";
@import "@fontsource-variable/geist";
@import "@fontsource-variable/plus-jakarta-sans";
* {
scrollbar-color: var(--color-scrollbar-handle) transparent;
@@ -46,22 +47,17 @@
}
.social-proof-marquee {
margin-inline: calc(50% - 50cqw);
overflow-x: clip;
position: relative;
}
.landing-content {
container-type: inline-size;
}
.social-proof-marquee::before,
.social-proof-marquee::after {
content: "";
position: absolute;
top: 0;
bottom: 0;
width: max(4rem, 8vw);
width: 4.5rem;
z-index: 1;
pointer-events: none;
}
@@ -112,7 +108,7 @@
/* Title font - centralized for easy changes */
.font-title {
font-family: inherit;
font-family: var(--font-display);
}
/* Inline code styling - scoped to prose content */
@@ -717,6 +713,8 @@
@theme {
--font-sans: "Geist Variable", ui-sans-serif, system-ui, sans-serif;
--font-display:
"Plus Jakarta Sans Variable", "Geist Variable", ui-sans-serif, system-ui, sans-serif;
--color-background: #101615;
--color-foreground: #fafafa;
@@ -728,6 +726,8 @@
--color-scrollbar-handle: #717574;
--color-primary: #239956;
--color-primary-foreground: #ffffff;
--color-accent-text: #6cb17b;
--color-brand-green: #20744a;
--color-secondary: #252b2a;
--color-secondary-foreground: #fafafa;
-4
View File
@@ -21,7 +21,6 @@ export class Children {
private readonly parentId: string,
private readonly cwd: string,
private readonly emit: (event: ProviderEvent) => void,
private readonly canProjectChild: () => boolean,
) {}
async update(item: WireItem): Promise<void> {
@@ -35,7 +34,6 @@ export class Children {
)
)
return;
if (!this.canProjectChild()) return;
const id = item.childSessionId;
if (!this.children.has(id)) {
const { session } = await this.host.request(
@@ -43,8 +41,6 @@ export class Children {
{ sessionId: id },
childSessionSchema,
);
// The parent can close while Muse reads the child.
if (!this.canProjectChild()) return;
this.emit({
type: "session.opened",
sessionId: id,
-1
View File
@@ -32,7 +32,6 @@ const capabilities = [
"session.persistence",
"permission",
"session.list",
"session.subsession",
] as const;
export interface MuseProviderOptions {
+7 -16
View File
@@ -142,13 +142,7 @@ export class Session {
const nativeId = response.session.sessionId;
this.liveState = {
nativeId,
children: new Children(
this.host,
this.options.id,
this.config.cwd,
this.options.emit,
() => !this.closing && this.options.capabilities.includes("session.subsession"),
),
children: new Children(this.host, this.options.id, this.config.cwd, this.options.emit),
timeline: new Timeline(
this.host,
nativeId,
@@ -400,15 +394,12 @@ export class Session {
.catch((error: unknown) => this.runtimeFailed(error));
}
private runtimeFailed(error: unknown): void {
// Closing the host can reject a notification's request. Let the close finish.
if (!this.closing) {
this.live().recovery.close();
this.options.emit({
type: "session.runtime_failed",
sessionId: this.options.id,
error: actionableError(error, this.options.launch),
});
}
this.live().recovery.close();
this.options.emit({
type: "session.runtime_failed",
sessionId: this.options.id,
error: actionableError(error, this.options.launch),
});
const interrupt = this.interruptCompletion;
if (interrupt) interrupt.reject(error instanceof Error ? error : new Error(String(error)));
}
+4 -16
View File
@@ -1,4 +1,4 @@
import { appendFileSync, existsSync, readFileSync } from "node:fs";
import { appendFileSync, readFileSync } from "node:fs";
import { createInterface } from "node:readline";
import path from "node:path";
import { fileURLToPath } from "node:url";
@@ -166,7 +166,9 @@ function parityResponse(frame) {
return true;
}
if (frame.method === "session/read") {
respondToChildRead(frame);
const result = responseFor(readFixture("phase3-child-read"), "session/read");
result.session.sessionId = frame.params.sessionId;
respond(frame, result);
return true;
}
if (frame.method === "usage/read") {
@@ -221,20 +223,6 @@ function parityResponse(frame) {
if (skillResponse(frame)) return true;
return false;
}
function respondToChildRead(frame) {
const result = responseFor(readFixture("phase3-child-read"), "session/read");
result.session.sessionId = frame.params.sessionId;
const releaseFile = process.env.MUSE_TEST_CHILD_READ_RELEASE;
if (releaseFile && !existsSync(releaseFile)) {
const waiting = setInterval(() => {
if (!existsSync(releaseFile)) return;
clearInterval(waiting);
respond(frame, result);
}, 10);
} else {
respond(frame, result);
}
}
function skillResponse(frame) {
if (frame.method === "skill/list") {
const skillRows =
+1 -16
View File
@@ -46,7 +46,6 @@ async function harness(
scenario = "text-reasoning",
env: Record<string, string> = {},
providerOptions?: Record<string, unknown>,
connectCapabilities: readonly string[] = PROVIDER_CAPABILITIES,
) {
const root = await mkdtemp(path.join(os.tmpdir(), "muse-provider-test-"));
roots.push(root);
@@ -64,7 +63,7 @@ async function harness(
const connection = await provider.connect({
launch,
versions: [1],
capabilities: connectCapabilities,
capabilities: PROVIDER_CAPABILITIES,
});
connections.push(connection);
const events: ProviderEvent[] = [];
@@ -1255,20 +1254,6 @@ for (const variant of ["tool", "dedicated", "workflow"]) {
).toHaveLength(1);
});
}
test("subagent children are not projected when session.subsession is not negotiated", async () => {
const h = await harness(
"subagent",
{ MUSE_TEST_CHILD: "tool" },
undefined,
PROVIDER_CAPABILITIES.filter((capability) => capability !== "session.subsession"),
);
await h.open();
await h.prompt();
await h.wait((e) => e.type === "session.turn" && e.state === "completed");
expect(h.events.filter((e) => e.type === "session.opened" && e.parentSessionId)).toHaveLength(0);
expect((await h.recorded()).filter((f) => f.method === "session/read")).toEqual([]);
});
test("gap backfill repairs a missing completion without duplicating item revisions", async () => {
const h = await harness("text-reasoning", { MUSE_TEST_GAP: "1" });
await h.open();
+16 -8
View File
@@ -447,21 +447,29 @@ paseo hub deploy -p <project> # Deploy an existing legacy project bundle
paseo hub logout # Remove the active stored CLI login
```
Run deploy from the repository root. By default it reads every direct `.paseo/triggers/*.yml` file in deterministic path order. It validates all triggers before installing them one at a time. If an installation fails after earlier ones succeeded, the error lists the installed files. `--dry-run` only validates; it does not create or activate revisions.
Run `paseo hub deploy` from the repository root. By default, it reads every direct `.paseo/triggers/*.yml` file in deterministic path order and validates all triggers before installing them one at a time.
Pass `-p, --project <slug>` for an existing legacy bundle: `.paseo/hub.yml`, direct `.paseo/workflows/*.yml` files, and referenced workflow partials. See [Deploy from the CLI](/docs/hub/configuration#deploy-from-the-cli).
If an installation fails after earlier ones succeeded, the error lists the installed files. `--dry-run` validates without creating or activating revisions. Pass `-p, --project <slug>` for an existing legacy project bundle, as described in [Deploy from the CLI](/docs/hub/configuration#deploy-from-the-cli).
`login` opens the Hub approval page and stores a durable organization-scoped CLI credential under `PASEO_HOME`. In an interactive terminal it offers to connect this daemon, then separately asks whether to allow Hub automations to run agents. Connection defaults to yes; execution permission defaults to no. It then links to Hub's **Triggers** page and prints `paseo hub init` for setup as code. `--json` and non-TTY login remain login-only and never prompt. The stored login is separate from the daemon relationship created by `connect`.
`paseo hub login` opens the Hub approval page and stores an organization-scoped CLI credential under `PASEO_HOME`. In an interactive terminal, it offers to connect this daemon (default yes) and separately asks whether to grant `hub.execute` (default no).
`init` requires a TTY. It signs in and connects the daemon as needed, then lists the organization's app connections that can back a starter trigger. One usable connection is selected automatically; with several, you choose a **Trigger connection**. If none is ready, setup sends you to **Hub → Apps** and stops before selecting an agent or writing files.
`--json` and non-TTY logins never prompt. The stored CLI login stays separate from the daemon relationship created by `connect`.
Setup asks which agent provider, model, and mode to run. Providers must be enabled and expose both a selectable model and an execution mode. Suggested model and mode entries are the daemon's defaults; a mode is still selected explicitly when there is no default. Hub validates the choice against the daemon before deploying, and accepts only Claude, Codex, and OpenCode for its unattended runs. `deploy` applies the same checks, so it needs the named daemon connected. Setup then asks for the identity allowed to trigger the bot: a GitHub username, Slack member ID, or Discord user ID. It validates the trigger, writes `.paseo/triggers/<provider>-help.yml`, and asks whether to deploy. Replacing that file requires confirmation; existing legacy bundles and other trigger files are preserved. See the [generated starter trigger](/docs/hub/configuration#generated-starter-trigger).
`paseo hub init` requires a TTY, signs in and connects the daemon as needed, and selects a ready integration (or sends you to **Hub → Apps** if none is ready). It then prompts for an enabled provider on your daemon that exposes both a selectable model and at least one execution mode.
Interactive logout checks the same-origin daemon relationship and asks whether to disconnect before deleting the login. Declining removes only the login. JSON and noninteractive logout never prompt or disconnect implicitly; `--disconnect-daemon` is the explicit automation path, and `--force` applies to that daemon disconnection. If a requested disconnection fails, the login is preserved.
Providers that report zero execution modes (such as Pi) are filtered out by `paseo hub init`, but can still be configured in the Hub dashboard or in `.paseo/triggers/*.yml` and deployed with `paseo hub deploy`.
Every command resolves and normalizes its destination before Hub or daemon work. Origin precedence is an explicit command origin or `--hub`, then `PASEO_HUB_URL`, then the active stored login origin, then the hosted default `https://hub.paseo.sh`. The hosted default never overrides an active login. Credential precedence is `--api-key <secret>`, then `PASEO_HUB_API_KEY`, then a stored login for the exact resolved origin. A stored credential is never sent to a different origin. API keys passed through flags or the environment are not stored.
Setup next asks for the allowed sender identity (GitHub username, Slack member ID, or Discord user ID), validates the trigger against the connected daemon, writes `.paseo/triggers/<provider>-help.yml`, and asks whether to deploy. Replacing an existing starter file requires confirmation while preserving other trigger files. See the [generated starter trigger](/docs/hub/configuration#generated-starter-trigger).
Human output reports the resolved destination before each action. JSON output keeps stdout machine-readable and includes the normalized Hub origin. Bundle diagnostics identify paths without printing configuration contents or credentials.
Interactive `paseo hub logout` checks for a daemon connected to the same Hub and asks whether to disconnect it before deleting the login. JSON and non-interactive logouts never prompt or disconnect unless you pass `--disconnect-daemon` (with optional `--force`). If disconnection fails, the login stays intact.
Every Hub command resolves its destination and credentials in order:
- Origin precedence: explicit `[url]` or `--hub`, then `PASEO_HUB_URL`, then the active stored login, then `https://hub.paseo.sh`.
- Credential precedence: `--api-key <secret>`, then `PASEO_HUB_API_KEY`, then a stored login matching the exact resolved origin.
- API keys passed via flags or environment variables are never written to disk, and stored credentials are never sent to another origin.
Human output prints the resolved destination before each action, while `--json` writes machine-readable output including the normalized Hub origin. Diagnostics name file paths without printing contents or credentials.
See [Daemons in Hub](/docs/hub/daemons), [Hub configuration](/docs/hub/configuration), and the [Hub public API](/docs/hub/api).
+16 -8
View File
@@ -426,21 +426,29 @@ paseo hub deploy -p <project> # Deploy an existing legacy project bundle
paseo hub logout # Remove the active stored CLI login
```
请在仓库根目录运行 deploy。它默认按确定的路径顺序读取所有直接位于 `.paseo/triggers/` 下的 `*.yml` 文件。它会先校验所有触发器,再逐个安装。如果在前面的安装成功之后某个安装失败,错误信息会列出已安装的文件。`--dry-run` 只做校验;它不会创建或激活修订。
请在仓库根目录运行 `paseo hub deploy`。它默认按确定的路径顺序读取所有直接位于 `.paseo/triggers/*.yml` 下的文件,并在逐个安装前先校验全部触发器。
对于已有的旧版文件包,传入 `-p, --project <slug>`:包括 `.paseo/hub.yml`、直接位于 `.paseo/workflows/` 下的 `*.yml` 文件,以及被引用的 workflow 片段。见[从 CLI 部署](/docs/hub/configuration#deploy-from-the-cli)。
如果在前面的安装成功之后某个安装失败,错误信息会列出已安装的文件。`--dry-run` 只做校验,不会创建或激活版本。对于已有的旧版项目文件包,请传入 `-p, --project <slug>`,参见[从 CLI 部署](/docs/hub/configuration#deploy-from-the-cli)。
`login` 会打开 Hub 的批准页面,并在 `PASEO_HOME` 下保存一个持久的、组织范围的 CLI 凭据。在交互式终端中,它会提议连接这个 daemon,然后单独询问是否允许 Hub 自动化在这里运行 Agent。连接默认为是;执行权限默认为否。随后它会链接到 Hub 的 **Triggers** 页面,并输出 `paseo hub init`,以便用代码完成设置。`--json` 和非 TTY 的登录只执行登录,从不提示。保存的登录与 `connect` 创建的 daemon 关系是分开的。
`paseo hub login` 会打开 Hub 批准页面,并在 `PASEO_HOME` 下保存组织级 CLI 凭据。在交互式终端中,它会询问是否连接此 daemon(默认为是),并单独询问是否授予 `hub.execute`(默认为否)。
`init` 需要 TTY。它会根据需要登录并连接 daemon,然后列出组织中可以支撑入门触发器的应用连接。只有一个可用连接时会自动选中;有多个时,由你选择一个 **Trigger connection**。如果没有任何连接就绪,设置会引导你前往 **Hub → Apps**,并在选择 Agent 或写入文件之前停止。
`--json` 和非 TTY 登录不会提示。保存的 CLI 登录与 `connect` 创建的 daemon 关系相互独立。
设置会询问要运行哪个 Agent Provider、模型和模式。Provider 必须已启用,并且同时提供可选择的模型和执行模式。建议的模型和模式条目是 daemon 的默认值;没有默认值时仍需显式选择模式。Hub 在部署前会对照 daemon 校验这项选择,并且其无人值守的运行只接受 Claude、Codex 和 OpenCode。`deploy` 会执行相同的检查,因此需要指定的 daemon 已连接。随后设置会询问允许触发机器人的身份:GitHub 用户名、Slack 成员 ID 或 Discord 用户 ID。它会校验触发器,写入 `.paseo/triggers/<provider>-help.yml`,并询问是否部署。替换该文件需要确认;已有的旧版文件包和其他触发器文件会被保留。见[生成的入门触发器](/docs/hub/configuration#generated-starter-trigger)。
`paseo hub init` 需要 TTY,按需登录并连接 daemon,并选择就绪的集成(若无可用集成则引导至 **Hub → Apps**)。随后它会提示你选择 daemon 上已启用、且同时提供可选模型和至少一个执行模式的 Provider。
交互式退出会检查同一地址的 daemon 关系,并在删除登录之前询问是否断开。选择否时只删除登录。JSON 和非交互式的退出从不提示,也不会隐式断开;`--disconnect-daemon` 是供自动化使用的显式方式,`--force` 作用于该 daemon 断开操作。如果请求的断开失败,登录会被保留。
不提供执行模式的 Provider(例如 Pi)会被 `paseo hub init` 过滤掉,但仍可在 Hub 控制台或 `.paseo/triggers/*.yml` 中配置并通过 `paseo hub deploy` 部署。
每个命令在执行 Hub 或 daemon 工作之前,都会解析并规范化它的目标。地址的优先级依次为:显式的命令地址或 `--hub`、`PASEO_HUB_URL`、当前保存的登录地址,最后是托管版默认地址 `https://hub.paseo.sh`。托管版默认地址从不会覆盖当前的登录。凭据的优先级依次为:`--api-key <secret>`、`PASEO_HUB_API_KEY`,然后是与解析出的地址完全匹配的已保存登录。保存的凭据从不会发送到其他地址。通过参数或环境变量传入的 API 密钥不会被保存。
接着设置会询问允许的发送者身份(GitHub 用户名、Slack 成员 ID 或 Discord 用户 ID),对照已连接的 daemon 校验触发器,写入 `.paseo/triggers/<provider>-help.yml` 并询问是否部署。替换已有入门文件需要确认,同时保留其他触发器文件。见[生成的入门触发器](/docs/hub/configuration#generated-starter-trigger)。
人类可读的输出会在每个操作之前报告解析出的目标。JSON 输出让 stdout 保持机器可读,并包含规范化后的 Hub 地址。文件包诊断会指出路径,但不会输出配置内容或凭据。
交互式 `paseo hub logout` 会检查连接到同一 Hub 的 daemon,并在删除登录前询问是否断开。JSON 和非交互式退出不会提示或断开,除非传入 `--disconnect-daemon`(可配合 `--force`)。如果断开失败,登录凭据会保留。
每个 Hub 命令都按顺序解析目标和凭据:
- 地址优先级:显式 `[url]` 或 `--hub`、`PASEO_HUB_URL`、当前已保存的登录,最后是 `https://hub.paseo.sh`。
- 凭据优先级:`--api-key <secret>`、`PASEO_HUB_API_KEY`,然后是与精确解析地址匹配的已保存登录。
- 通过参数或环境变量传入的 API 密钥永远不会写入磁盘,已保存的凭据也不会发送到其他地址。
人类可读输出会在每个操作前打印解析出的目标,而 `--json` 会输出包含规范化 Hub 地址的机器可读结果。诊断信息仅指出文件路径,不输出文件内容或凭据。
见 [Hub 中的 daemon](/docs/hub/daemons)、[Hub 配置](/docs/hub/configuration)和 [Hub 公开 API](/docs/hub/api)。
+22 -32
View File
@@ -1,53 +1,43 @@
---
title: Hub activity
description: Read what Hub did with an event, tell a filtered event from an unrouted one, and debug a trigger that did nothing.
description: Inspect trigger runs, distinguish filtered events from unrouted ones, and debug a trigger that did not run.
nav: Activity
order: 72
order: 75
category: Hub
---
# Hub activity
Every event Hub accepts is recorded, whether or not it ran anything. That record is how you debug a trigger.
Hub records every accepted event, whether or not it started a run. Use **Activity** and **Integrations** to inspect deliveries and debug triggers.
## Where to look
**Project → Activity** lists routed trigger runs and their execution state.
**Activity** lists organization trigger runs, including the triggering source, daemon, execution status, replies, and errors.
**Connections → Known unrouted events** is the organization-level view of accepted provider events that did not start a configured trigger. Hub records one of four bounded reasons:
**Integrations → Known unrouted events** lists accepted provider events that did not start a trigger. Hub records one of four reasons:
| Reason | Meaning |
| --------------------------- | ------------------------------------------------------------ |
| `no_project_route` | No project route is configured for the event |
| `no_trigger_for_source` | No configured trigger handles that event source |
| `trigger_filters_rejected` | A trigger handles the source, but its filters rejected it |
| `configuration_unavailable` | A relevant configuration or connection could not be resolved |
| `no_project_route` | No enabled route matched the event's integration or resource |
| `no_trigger_for_source` | No enabled trigger handles that event source |
| `trigger_filters_rejected` | A trigger matched the source, but its filters rejected it |
| `configuration_unavailable` | A referenced trigger or integration could not be resolved |
## Nothing happened when I mentioned the bot
## Nothing happened when an event arrived
Work down this list.
Check these items in order:
1. **Is the event in the project's Activity?** If not, check **Connections → Known unrouted events** and use its reason to distinguish routing, source, filter, and configuration failures.
2. **Is the event anywhere at all?** If not, the event never reached Hub. Check the provider's own delivery log: GitHub's App → Advanced → Recent Deliveries, or Slack's Event Subscriptions page. Then check that the app is subscribed to that event type.
3. **Is your user in `from_users`?** This is the most common cause. GitHub uses your login; Slack and Discord use the user ID, not the display name. See [find your Slack IDs](/docs/hub/triggers/slack#find-your-slack-ids) and [find your Discord IDs](/docs/hub/triggers/discord#find-your-discord-ids).
4. **Did the invocation match?** On GitHub, `contains` must appear in the comment body. On Slack and Discord the bot must be mentioned, and `pattern` or its legacy `contains` alias must prefix the text after the mention.
5. **Is the configuration you think is active actually active?** The Configuration tab shows the active revision and the last sync attempt. A failed push leaves the old revision serving.
6. **Is the daemon connected?** An offline daemon fails dispatch with `daemon_not_connected`.
7. **Did it run and stop early?** Compare the execution with the step's authored `idle_timeout` and `max_runtime`, and the workflow's `max_runtime`. All three limits are explicit in the workflow.
8. **Did it run, but deliver nothing?** Check the step's prompt. An agent that is not told to call `hub.reply` and `hub.finish_execution` can answer in its own transcript and never report back. See [Tell the agent which tool to call](/docs/hub/workflows#tell-the-agent-which-tool-to-call).
1. Open **Activity**. If the event is missing there, check **Integrations → Known unrouted events** and read the recorded reason.
2. If the event does not appear in either view, the provider never reached Hub. Check the provider delivery log (GitHub **App → Advanced → Recent Deliveries**, Linear webhook logs, or Slack **Event Subscriptions**) and make sure that the app subscribes to that event type.
3. Verify `from_users`. GitHub uses login names, while Linear, Slack, and Discord use user IDs ([Linear](/docs/hub/triggers/linear#filters-and-linear-uuids), [Slack](/docs/hub/triggers/slack#find-your-slack-ids), [Discord](/docs/hub/triggers/discord#find-your-discord-ids)).
4. Verify text filters (`contains`, `pattern`, and GitHub `exclude_contains`). On Slack and Discord, the message must mention the bot and any `pattern` must follow the mention.
5. Verify that the trigger is enabled under **Triggers**.
6. Verify that the target daemon is connected under **Daemons** and holds the `hub.execute` permission.
7. If the run started and stopped early, compare its duration against `max_runtime`, `idle_timeout`, and `startup_timeout`.
8. If the run finished without posting back, check `run.prompt`. The prompt must tell the agent to call `reply` (or `slack_post` / `discord_post`) and `finish_execution`.
## Sync failures
## Webhook and schedule runs
The Configuration tab shows the latest sync state:
Inbound webhook deliveries appear in **Activity** under `webhook.received`. If an HTTP `POST` returns an error status (`400`, `401`, `403`, `409`, `413`, or `429`), see [Inbound webhooks](/docs/hub/triggers/webhooks#request-limits-and-responses).
| State | What to do |
| ----------------------- | ------------------------------------------------------------------------ |
| Fetch failed | The file is missing at that commit, or the App can't read the repository |
| Invalid | Validation failed, or the config names something unreachable |
| Superseded push ignored | A newer commit already moved the branch head; nothing is wrong |
"Names something unreachable" is usually a repository the installation doesn't cover, a daemon that was renamed, or a connection slug that no longer exists. See [How Hub works](/docs/hub/concepts).
## Nothing is retried
Hub does not queue events. A dispatch that fails because the daemon was offline stays failed, so trigger it again once the daemon is back.
Scheduled runs appear in **Activity** under `schedule.tick`. While a scheduled run is still active, Hub skips newly due occurrences for that trigger until the active run completes or fails.
+23 -33
View File
@@ -1,51 +1,41 @@
---
title: Hub 活动
description: 查看 Hub 如何处理一个事件,区分被过滤和未路由的事件,并排查没有任何反应的触发器。
description: 查看触发器运行记录、区分被过滤事件与未路由事件,以及排查未触发的问题。
nav: 活动
---
# Hub 活动 {#hub-activity}
Hub 接受的每个事件都会被记录,无论它是否运行了任何内容。这份记录就是你排查触发器的依据。
Hub 会记录每一次已接受的事件,无论它是否启动了运行。使用 **Activity** 和 **Integrations** 查看投递并排查触发器。
## 在哪里查看 {#where-to-look}
**Project → Activity** 列出已路由的触发器运行及其执行状态。
**Activity** 列出组织的触发器运行记录,包括触发来源、daemon、执行状态、回复和错误。
**Connections → Known unrouted events** 是组织级视图,列出已接受但没有启动任何已配置触发器的 Provider 事件。Hub 会记录以下四种原因之一:
**Integrations → Known unrouted events** 列出已接受但未启动触发器的 Provider 事件。Hub 记录以下四种原因之一:
| 原因 | 含义 |
| --------------------------- | -------------------------------------------- |
| `no_project_route` | 没有为该事件配置项目路由 |
| `no_trigger_for_source` | 没有已配置的触发器处理该事件来源 |
| `trigger_filters_rejected` | 有触发器处理该来源,但它的过滤器拒绝了该事件 |
| `configuration_unavailable` | 无法解析相关的配置或连接 |
| 原因 | 含义 |
| --------------------------- | -------------------------------------- |
| `no_project_route` | 没有已启用的路由匹配该事件的集成或资源 |
| `no_trigger_for_source` | 没有已启用的触发器处理该事件来源 |
| `trigger_filters_rejected` | 有触发器处理该来源,但被过滤条件拒绝 |
| `configuration_unavailable` | 无法解析引用的触发器或集成 |
## 我提及了机器人,但什么都没发生 {#nothing-happened-when-i-mentioned-the-bot}
## 事件到达后没有任何反应 {#nothing-happened-when-an-event-arrived}
按这个列表逐项排查。
按以下顺序排查:
1. **事件是否出现在项目的 Activity 中?** 如果没有,请查看 **Connections → Known unrouted events**,根据其中的原因区分路由、来源、过滤器和配置方面的失败。
2. **事件是否出现在任何地方?** 如果没有,说明事件从未到达 Hub。请查看 Provider 自己的投递日志:GitHub 的 App → Advanced → Recent Deliveries,或 Slack 的 Event Subscriptions 页面。然后确认应用订阅了该事件类型。
3. **你的用户是否在 `from_users` 中?** 这是最常见的原因。GitHub 使用你的登录名;Slack 和 Discord 使用用户 ID,而不是显示名称。参见[查找 Slack ID](/docs/hub/triggers/slack#find-your-slack-ids) 和[查找 Discord ID](/docs/hub/triggers/discord#find-your-discord-ids)。
4. **调用是否匹配?** 在 GitHub 上,评论正文中必须出现 `contains`。在 Slack 和 Discord 上,必须提及机器人,并且提及之后的文本必须以 `pattern`(或其旧别名 `contains`)开头。
5. **你以为生效的配置是否真的生效?** Configuration 标签页显示当前生效的版本和上一次同步尝试。推送失败时,旧版本会继续生效。
6. **daemon 是否已连接?** daemon 离线时派发会失败,并报告 `daemon_not_connected`。
7. **是否运行了但提前停止?** 把这次执行与 step 中编写的 `idle_timeout`、`max_runtime` 以及 workflow 的 `max_runtime` 进行比较。这三个限制都在 workflow 中显式声明。
8. **是否运行了但什么都没投递?** 检查 step 的提示词。没有被告知调用 `hub.reply` 和 `hub.finish_execution` 的 Agent,可能只在自己的对话记录中回答,而从不回报。参见[告诉 Agent 调用哪个工具](/docs/hub/workflows#tell-the-agent-which-tool-to-call)。
1. 打开 **Activity**。如果事件未出现在那里,请检查 **Integrations → Known unrouted events** 并查看记录的原因。
2. 如果两处都没有,说明事件从未到达 Hub。检查 Provider 自己的投递日志(GitHub **App → Advanced → Recent Deliveries**、Linear webhook 日志或 Slack **Event Subscriptions**),并确认应用已订阅对应事件类型。
3. 检查 `from_users`。GitHub 使用登录名,Linear、Slack 和 Discord 使用用户 ID(参见 [Linear](/docs/hub/triggers/linear#filters-and-linear-uuids)、[Slack](/docs/hub/triggers/slack#find-your-slack-ids)、[Discord](/docs/hub/triggers/discord#find-your-discord-ids))。
4. 检查文本过滤条件(`contains`、`pattern` 以及 GitHub 的 `exclude_contains`)。在 Slack 和 Discord 上,消息必须提及机器人,且任何 `pattern` 都必须紧跟在提及之后。
5. 在 **Triggers** 下确认触发器已启用。
6. 在 **Daemons** 下确认目标 daemon 已连接并拥有 `hub.execute` 权限。
7. 如果运行已启动但提前停止,请将其持续时间与 `max_runtime`、`idle_timeout` 和 `startup_timeout` 进行对比。
8. 如果运行已完成但没有回复,请检查 `run.prompt`。提示词必须明确告诉 Agent 调用 `reply`(或 `slack_post` / `discord_post`)和 `finish_execution`。
## 同步失败 {#sync-failures}
## Webhook 与定时运行 {#webhook-and-schedule-runs}
Configuration 标签页显示最近的同步状态:
入站 webhook 投递会以 `webhook.received` 出现在 **Activity** 中。如果 HTTP `POST` 返回错误状态码(`400`、`401`、`403`、`409`、`413` 或 `429`),参见[入站 webhook](/docs/hub/triggers/webhooks#request-limits-and-responses)。
| 状态 | 处理方式 |
| ----------------------- | ---------------------------------------- |
| Fetch failed | 该提交中缺少文件,或者 App 无法读取仓库 |
| Invalid | 校验失败,或者配置引用了无法访问的内容 |
| Superseded push ignored | 更新的提交已经移动了分支头;没有任何问题 |
“引用了无法访问的内容”通常是指安装未覆盖的仓库、已被重命名的 daemon,或已不存在的连接 slug。参见 [Hub 工作原理](/docs/hub/concepts)。
## 不会重试 {#nothing-is-retried}
Hub 不会让事件排队。因 daemon 离线而失败的派发会一直保持失败,所以请在 daemon 恢复后重新触发。
定时运行会以 `schedule.tick` 出现在 **Activity** 中。当某次定时运行仍在进行时,Hub 会跳过该触发器新到期的计划,直到当前运行完成或失败。
+59 -174
View File
@@ -1,56 +1,46 @@
---
title: Hub public API
description: Use organization credentials to install triggers, manage legacy configuration, dispatch runs, and enroll daemons.
description: Authenticate with organization credentials to validate and install triggers, rotate webhook secrets, dispatch manual runs, and enroll daemons.
nav: Public API
order: 79
order: 83
category: Hub
---
# Hub public API
The Hub public API lets automation operate on triggers, projects, and daemons in one
organization. Set the Hub origin in `PASEO_HUB_URL` below, for example
`https://hub.example.com`.
The Hub public API lets scripts and CI pipelines manage triggers, webhook secrets, manual runs, and daemon enrollment for one organization. Set `PASEO_HUB_URL` to your Hub origin, such as `https://hub.example.com`.
## API reference
- [Interactive API reference](https://hub.paseo.sh/api/reference)
- [OpenAPI 3.1 document](https://hub.paseo.sh/api/openapi.json)
These are the canonical reference endpoints for the hosted Paseo Hub. A self-hosted Hub exposes the same `/api/reference` and `/api/openapi.json` paths on its own origin.
A self-hosted Hub serves the same `/api/reference` and `/api/openapi.json` endpoints on its own origin.
## Authentication
Run `paseo hub login [origin]` for interactive CLI access. After browser approval, Paseo stores a durable, revocable organization credential under `PASEO_HOME` for that exact origin. Without an explicit origin, the CLI uses `PASEO_HUB_URL`, then the active stored login, then `https://hub.paseo.sh`.
For interactive CLI access, run `paseo hub login [origin]`. Paseo stores a revocable organization credential under `PASEO_HOME` for that exact origin.
For automation, create an organization API key from the Hub dashboard under **API keys**. Both credential types are bearer tokens:
For automation, create an organization API key in Hub under **Settings → API keys**. Send either credential as a Bearer token:
```http
Authorization: Bearer paseo_pk_...
Content-Type: application/json
```
API keys are organization-scoped. The organization that owns the key determines
which projects and daemon enrollment tokens it can reach; there is no
organization ID to add to these requests. A project slug from another
organization is not accessible through the key.
API keys are scoped to one organization and one or more selected scopes:
Each key has one or more selectable scopes:
| Scope | Operations permitted |
| ------------------------ | ---------------------------------------------------------------- |
| `configuration:validate` | List triggers, list resolvable resources, and validate triggers. |
| `configuration:install` | Install triggers and create or rotate trigger webhook secrets. |
| `runs:dispatch` | Dispatch a configured `manual.run` trigger. |
| `daemons:enroll` | Issue a short-lived daemon enrollment token. |
| `projects:read` | List projects in the organization. |
| Scope | Operation |
| ------------------------ | --------------------------------------------------------------------- |
| `projects:read` | List active projects in the organization. |
| `configuration:validate` | Validate triggers or legacy configuration without changing Hub state. |
| `configuration:install` | Install triggers or replace a legacy project's configuration. |
| `runs:dispatch` | Dispatch a configured manual trigger for a project. |
| `daemons:enroll` | Issue a short-lived daemon enrollment token. |
API keys do not grant dashboard sign-in and cannot manage integrations or organization members.
API keys do not grant dashboard access. They cannot manage connections,
projects, or organization members.
CLI credentials have the current CLI operation scopes and remain revocable independently of daemon relationships. `paseo hub logout` deletes the active local CLI credential; it does not revoke or disconnect the daemon identity.
API failures use RFC 9457 problem details. Missing, invalid, or revoked credentials return `401` with `application/problem+json`:
API errors return RFC 9457 `application/problem+json` with an `X-Request-ID` header. Missing, invalid, or revoked credentials return `401` with `WWW-Authenticate: Bearer`:
```json
{
@@ -63,23 +53,23 @@ API failures use RFC 9457 problem details. Missing, invalid, or revoked credenti
}
```
A valid key without the scope required by an endpoint returns `403` in the same format.
A valid credential missing the required scope returns `403` in the same format.
## Trigger validation and installation
## Trigger list, validation, and installation
`paseo hub deploy --dry-run` validates each `.paseo/triggers/*.yml` file through `POST /api/v1/triggers/validate`. `paseo hub deploy` validates all files first, then installs each through `POST /api/v1/triggers/install`.
- `GET /api/v1/triggers` (`configuration:validate`) lists active organization triggers and their deployable YAML documents.
- `POST /api/v1/triggers/validate` (`configuration:validate`) validates one self-contained trigger YAML document without changing Hub state.
- `POST /api/v1/triggers/install` (`configuration:install`) validates and installs one trigger, creating or updating it by its YAML `name`.
Both endpoints accept one self-contained document:
`POST /api/v1/triggers/validate` and `POST /api/v1/triggers/install` accept the same JSON request body:
```json
{
"yaml": "name: manual-task\nenabled: true\non:\n manual.run: {}\nrun:\n target: { daemon: my-macbook, cwd: /workspace }\n agent: { provider: codex, model: gpt-5, mode: full-access }\n prompt: Complete the task and call hub.finish_execution.\n max_runtime: 1h\n idle_timeout: 5m\n"
"yaml": "name: manual-task\nenabled: true\non:\n manual.run: {}\nrun:\n target: { daemon: my-macbook, cwd: /workspace }\n agent: { provider: codex, mode: full-access }\n prompt: |\n Complete the task and call finish_execution.\n ${{ paseo.prompt }}\n max_runtime: 1h\n idle_timeout: 5m\n"
}
```
Use a daemon slug and agent runtime available in your organization. Both operations ask the named daemon to check the agent, so it has to be connected and hold `hub.execute`; an agent it cannot run is a field issue rather than a failed first run. See [Saving checks the agent against the daemon](/docs/hub/triggers#saving-checks-the-agent-against-the-daemon). Validation requires `configuration:validate` and returns `200` with `{ "name": "manual-task", "valid": true }`.
Installation requires `configuration:install`. It creates or updates the organization's trigger by the YAML `name` and returns `201`:
Both endpoints ask the target daemon to validate `run.agent`, so that daemon must be connected and hold `hub.execute`. Validation returns `200` with `{ "name": "manual-task", "valid": true }`. Installation returns `201`:
```json
{
@@ -91,143 +81,64 @@ Installation requires `configuration:install`. It creates or updates the organiz
}
```
Invalid YAML or an unknown organization resource returns `422` with field issues. Each installation is a separate request; a later failure does not undo earlier successful installs. See [Deploy from the CLI](/docs/hub/configuration#deploy-from-the-cli).
Invalid YAML, unknown integrations, or rejected agent settings return `422` with field issues. `paseo hub deploy --dry-run` and `paseo hub deploy` call these endpoints for `.paseo/triggers/*.yml`.
## Project list
## Webhook secrets
`GET /api/v1/projects` returns active projects in the bearer credential's organization. `paseo hub projects` renders the projects as a table. With `--json`, it returns `{ "origin": "...", "projects": [...] }` so even an empty result records the resolved Hub.
```json
{
"projects": [
{
"id": "00000000-0000-4000-8000-000000000000",
"slug": "my-project",
"name": "My project"
}
]
}
```
## Legacy configuration validation
`POST /api/v1/configurations/validate` accepts the same `projectSlug` and complete `files` bundle as configuration install. It performs the same compilation and resource resolution without recording a revision or changing the active configuration.
On success, Hub returns `200`:
```json
{
"projectSlug": "my-project",
"valid": true
}
```
`paseo hub deploy --project <slug> --dry-run` calls this endpoint with the identical locally resolved payload that a deployment would send.
## Legacy configuration install
`configuration:install` validates the supplied canonical bundle, stores the exact authored files, and activates a new revision.
```http
POST /api/v1/configurations/install
```
`POST /api/v1/triggers/webhook-secret` (`configuration:install`) creates or rotates the Bearer secret for a saved `webhook.received` trigger.
Request body:
```json
{
"projectSlug": "my-project",
"files": [
{
"path": ".paseo/hub.yml",
"content": "environments:\n production:\n kind: daemon\n daemon: build-server\n cwd: /workspace\nagents:\n codex:\n provider: codex\n"
},
{
"path": ".paseo/workflows/deploy.yml",
"content": "name: deploy\non: manual.run\nmax_runtime: 2h\nfilters:\n from_users: [automation]\nsteps:\n - id: deploy\n environment: production\n max_runtime: 90m\n idle_timeout: 10m\n agent: codex\n prompt:\n - include: partials/safety.md\n"
},
{
"path": ".paseo/workflows/partials/safety.md",
"content": "Follow the safety checklist."
}
]
"triggerId": "00000000-0000-4000-8000-000000000001"
}
```
`projectSlug` picks the target project; the bearer credential fixes the organization. `files` contains `.paseo/hub.yml`, every direct workflow `.yml`, and each referenced workflow partial. Hub rejects missing, extra, duplicate, unsafe, or noncanonical paths.
Limits:
- Bundle: at most 100 files.
- File path: at most 512 characters.
- File content: at most 1,000,000 characters.
- Prompt partials: at most 1,000,000 bytes each and 5,000,000 bytes in total.
On success, Hub returns `201`:
On success, Hub returns `200` with `Cache-Control: no-store`:
```json
{
"projectSlug": "my-project",
"versionId": "00000000-0000-4000-8000-000000000000",
"version": 3,
"active": true
"path": "/webhooks/wh_0123456789abcdef0123456789abcdef",
"secret": "whsec_..."
}
```
Common responses are `400` for a missing or malformed body, `404` for an inactive or unknown project in the key's organization, and `422` for invalid YAML or an invalid configuration. Validation problem details include field issues. A failed install does not replace the active revision.
Example:
```bash
curl --fail-with-body -sS -X POST "$PASEO_HUB_URL/api/v1/configurations/install" \
-H "Authorization: Bearer $PASEO_HUB_API_KEY" \
-H "Content-Type: application/json" \
--data @configuration-install.json
```
`paseo hub deploy -p <project>` selects this legacy endpoint with the discovered local bundle. The command uses an exact-origin stored login when flags and environment credentials are absent. See [Deploy from the CLI](/docs/hub/configuration#deploy-from-the-cli).
Each call replaces any previous secret immediately and shows the new secret only once. See [Inbound webhooks](/docs/hub/triggers/webhooks) for sending deliveries to `/webhooks/wh_...`.
## Manual run dispatch
`runs:dispatch` dispatches a configured `manual.run` trigger for a project.
The trigger must exist in the active configuration, and `actor` must be listed
in that trigger's `filters.from_users` allowlist.
```http
POST /api/v1/manual-runs
```
Request body:
`POST /api/v1/manual-runs` (`runs:dispatch`) starts a configured `manual.run` trigger. `actor` must match that trigger's `filters.from_users` allowlist (or `*` when omitted).
```json
{
"projectSlug": "my-project",
"expectedVersionId": "00000000-0000-4000-8000-000000000000",
"trigger": "deploy",
"projectSlug": "default",
"trigger": "manual-task",
"actor": "automation",
"deliveryKey": "deploy-2026-08-04-001",
"deliveryKey": "manual-task-2026-09-09-001",
"input": "repo=project investigate the failed sync"
}
```
- `expectedVersionId` is optional. When supplied, Hub rejects the dispatch if that revision is no longer active.
- `input` is the same string a provider message uses: leading `key=value` tokens are parsed as declared inputs, and the remainder becomes `${{ paseo.prompt }}`.
- `deliveryKey` should be unique and stable per dispatch. Hub uses it for durable deduplication, but does not promise exactly-once dispatch or replay of an earlier response.
- `deliveryKey` provides durable deduplication scoped to your organization and project.
- `input` accepts leading `key=value` tokens for declared `inputs` followed by prompt text.
Omit `expectedVersionId` for standalone triggers. Passing the `revisionId` from trigger installation returns HTTP `409` (`configuration_changed`), even when the trigger is unchanged.
For legacy project bundles, `expectedVersionId` is optional. Set it to the active project configuration revision ID to reject dispatch if the configuration changes.
On success, Hub returns `200`:
```json
{
"deliveryKey": "deploy-2026-08-04-001",
"deliveryKey": "manual-task-2026-09-09-001",
"providerEventReceiptId": "00000000-0000-4000-8000-000000000000",
"triggerRunId": "00000000-0000-4000-8000-000000000000",
"configuredTriggerName": "deploy",
"configuredTriggerName": "manual-task",
"workflowStatus": "running"
}
```
Common responses are `400` for an invalid request, `403` when the actor is not allowed by the trigger, `404` for an unknown project, configuration, or trigger, and `409` when the daemon is offline, the expected configuration is no longer current, or dispatch conflicts. Each uses the problem-details shape above.
Example:
```bash
@@ -235,39 +146,17 @@ curl --fail-with-body -sS -X POST "$PASEO_HUB_URL/api/v1/manual-runs" \
-H "Authorization: Bearer $PASEO_HUB_API_KEY" \
-H "Content-Type: application/json" \
--data '{
"projectSlug": "my-project",
"trigger": "deploy",
"projectSlug": "default",
"trigger": "manual-task",
"actor": "automation",
"deliveryKey": "deploy-2026-08-04-001",
"input": "repo=project investigate the failed sync"
"deliveryKey": "manual-task-2026-09-09-001",
"input": "investigate the failed sync"
}'
```
See [Hub workflows](/docs/hub/workflows) for input types, defaults, choices,
rejected input, and manual invocation examples.
## Daemon enrollment
`daemons:enroll` issues a short-lived enrollment token for a daemon. The API
key mints this token; it is not the daemon's long-lived credential and must not
be used as one.
```http
POST /api/v1/daemons/enrollment-tokens
```
No request body is required. On success, Hub returns `201`:
```json
{
"token": "short-lived-enrollment-token",
"expiresAt": "2026-08-04T12:10:00.000Z"
}
```
The token expires after 10 minutes and is consumed when the daemon enrolls.
`paseo hub connect [origin]` performs this request with `--api-key`, `PASEO_HUB_API_KEY`, or the matching stored login, then passes the one-time token to the daemon's enrollment operation. The daemon generates and keeps its own relationship credential.
`POST /api/v1/daemons/enrollment-tokens` (`daemons:enroll`) issues a single-use enrollment token that expires in 10 minutes. No request body is required.
```bash
curl --fail-with-body -sS -X POST \
@@ -275,21 +164,17 @@ curl --fail-with-body -sS -X POST \
-H "Authorization: Bearer $PASEO_HUB_API_KEY"
```
Direct API consumers can pass the returned token to the daemon enrollment protocol. The Paseo CLI intentionally does not accept raw enrollment tokens; `connect` owns the authenticated single-flow exchange.
Response (`201`):
An enrollment token cannot be reused. Revoking the API key immediately rejects
future API requests and expires any unconsumed enrollment tokens that key
issued. A race between revocation and issuance is resolved by Hub before a new
token is stored.
```json
{
"token": "short-lived-enrollment-token",
"expiresAt": "2026-09-09T12:10:00.000Z"
}
```
## Keys, scopes, and audit information
`paseo hub connect [origin]` calls this endpoint automatically and exchanges the token for the daemon's own long-lived relationship credential. Revoking the API key immediately blocks new API calls and expires any unconsumed enrollment tokens it issued.
The complete API-key secret is shown once, immediately after creation. Store it
in your deployment's secret manager; Hub does not show it again. The dashboard
retains only the key's prefix and shows its selected scopes, creation time,
last-used time, and status.
## Keys and audit trails
Hub updates `last used` after a key successfully authenticates for a scoped API
operation. API operations retain the key attribution in Hub's audit evidence,
so configuration revisions, manual dispatches, and daemon enrollment tokens
can be traced to the organization key that created them.
Hub displays an API key secret once at creation time. The dashboard keeps only the key prefix, scopes, creation time, last-used timestamp, and revocation status. Hub records key attribution on trigger installations, webhook rotations, manual dispatches, and daemon enrollment tokens.
+62 -157
View File
@@ -1,48 +1,44 @@
---
title: Hub 公开 API
description: 使用组织凭据安装触发器、管理旧版配置、发起运行和注册 daemon。
description: 使用组织凭据校验和安装触发器、轮换 webhook 密钥、派发手动运行并注册 daemon。
nav: 公开 API
---
# Hub 公开 API {#hub-public-api}
Hub 公开 API 让自动化可以操作一个组织中的触发器、项目和 daemon。下文用 `PASEO_HUB_URL` 表示 Hub 的地址,例如 `https://hub.example.com`。
Hub 公开 API 让脚本和 CI 流水线能够管理一个组织的触发器、webhook 密钥、手动运行和 daemon 注册。请将 `PASEO_HUB_URL` 设为你的 Hub 地址,例如 `https://hub.example.com`。
## API 参考 {#api-reference}
- [交互式 API 参考](https://hub.paseo.sh/api/reference)
- [OpenAPI 3.1 文档](https://hub.paseo.sh/api/openapi.json)
这些是托管版 Paseo Hub 的标准参考端点。自托管的 Hub 在它自己的地址上提供相同的 `/api/reference` 和 `/api/openapi.json` 路径。
自托管 Hub 在自己的地址下提供相同的 `/api/reference` 和 `/api/openapi.json` 端点。
## 身份验证 {#authentication}
## 认证 {#authentication}
运行 `paseo hub login [origin]` 获得交互式的 CLI 访问权限。在浏览器中批准后,Paseo 会在 `PASEO_HOME` 下为这个确切的地址保存一个持久、可撤销的组织凭据。未显式指定地址时,CLI 依次使用 `PASEO_HUB_URL`、当前保存的登录,然后是 `https://hub.paseo.sh`。
交互式 CLI 访问请运行 `paseo hub login [origin]`。Paseo 会在 `PASEO_HOME` 下为该精确地址保存一个可撤销的组织凭据。
用于自动化时,请在 Hub 控制台的 **API keys** 下创建组织 API 密钥。两种凭据都是 bearer token:
自动化场景请在 Hub 的 **Settings → API keys** 下创建组织 API 密钥。两种凭据都作为 Bearer 令牌发送:
```http
Authorization: Bearer paseo_pk_...
Content-Type: application/json
```
API 密钥的作用域是组织。拥有该密钥的组织决定了它能访问哪些项目和 daemon 注册令牌;这些请求中不需要添加组织 ID。通过该密钥无法访问其他组织的项目 slug。
API 密钥限定在单个组织内,并绑定所选的一个或多个权限范围:
每个密钥有一个或多个可选的权限范围:
| 权限范围 | 允许的操作 |
| ------------------------ | ----------------------------------------------- |
| `configuration:validate` | 列出触发器、列出可解析资源并校验触发器。 |
| `configuration:install` | 安装触发器,以及创建或轮换触发器 webhook 密钥。 |
| `runs:dispatch` | 派发已配置的 `manual.run` 触发器。 |
| `daemons:enroll` | 签发短期 daemon 注册令牌。 |
| `projects:read` | 列出组织中的项目。 |
| 权限范围 | 操作 |
| ------------------------ | --------------------------------------- |
| `projects:read` | 列出组织中的活动项目。 |
| `configuration:validate` | 校验触发器或旧版配置,不改变 Hub 状态。 |
| `configuration:install` | 安装触发器,或替换旧版项目的配置。 |
| `runs:dispatch` | 为项目发起一个已配置的手动触发器。 |
| `daemons:enroll` | 签发一个短期有效的 daemon 注册令牌。 |
API 密钥不能用于登录控制台,也不能管理集成或组织成员。
API 密钥不授予控制台访问权限。它们不能管理连接、项目或组织成员。
CLI 凭据拥有当前 CLI 操作所需的权限范围,并且可以独立于 daemon 关系单独撤销。`paseo hub logout` 会删除当前的本地 CLI 凭据;它不会撤销或断开 daemon 身份。
API 失败时使用 RFC 9457 问题详情格式。缺失、无效或已撤销的凭据返回 `401`,类型为 `application/problem+json`:
API 错误返回 RFC 9457 `application/problem+json` 格式并带有 `X-Request-ID` 响应头。缺少、无效或已撤销的凭据返回 `401` 和 `WWW-Authenticate: Bearer`:
```json
{
@@ -55,23 +51,23 @@ API 失败时使用 RFC 9457 问题详情格式。缺失、无效或已撤销的
}
```
有效但缺少端点所需权限范围的密钥会以相同格式返回 `403`。
有效凭据但缺少所需权限范围时,以相同格式返回 `403`。
## 触发器校验和安装 {#trigger-validation-and-installation}
## 触发器列表、校验与安装 {#trigger-list-validation-and-installation}
`paseo hub deploy --dry-run` 通过 `POST /api/v1/triggers/validate` 校验每个 `.paseo/triggers/*.yml` 文件。`paseo hub deploy` 先校验所有文件,再通过 `POST /api/v1/triggers/install` 逐个安装。
- `GET /api/v1/triggers`(`configuration:validate`)列出组织的活动触发器及其可部署的 YAML 文档。
- `POST /api/v1/triggers/validate`(`configuration:validate`)校验单个自包含触发器 YAML 文档,不修改 Hub 状态。
- `POST /api/v1/triggers/install`(`configuration:install`)校验并安装单个触发器,按其 YAML `name` 创建或更新。
两个端点都接受一份自包含的文档:
`POST /api/v1/triggers/validate` 和 `POST /api/v1/triggers/install` 接受相同的 JSON 请求体:
```json
{
"yaml": "name: manual-task\nenabled: true\non:\n manual.run: {}\nrun:\n target: { daemon: my-macbook, cwd: /workspace }\n agent: { provider: codex, model: gpt-5, mode: full-access }\n prompt: Complete the task and call hub.finish_execution.\n max_runtime: 1h\n idle_timeout: 5m\n"
"yaml": "name: manual-task\nenabled: true\non:\n manual.run: {}\nrun:\n target: { daemon: my-macbook, cwd: /workspace }\n agent: { provider: codex, mode: full-access }\n prompt: |\n Complete the task and call finish_execution.\n ${{ paseo.prompt }}\n max_runtime: 1h\n idle_timeout: 5m\n"
}
```
请使用你的组织中可用的 daemon slug 和 Agent 运行时。两个操作都会请指定的 daemon 检查 Agent,因此它必须已连接并持有 `hub.execute`;它无法运行的 Agent 会作为字段问题报告,而不是在第一次运行时失败。见[保存时会对照 daemon 检查 Agent](/docs/hub/triggers#saving-checks-the-agent-against-the-daemon)。校验需要 `configuration:validate`,并返回 `200` 和 `{ "name": "manual-task", "valid": true }`。
安装需要 `configuration:install`。它按 YAML 中的 `name` 创建或更新组织的触发器,并返回 `201`:
两个端点都会请目标 daemon 校验 `run.agent`,因此该 daemon 必须在线且持有 `hub.execute`。校验成功返回 `200` 和 `{ "name": "manual-task", "valid": true }`。安装成功返回 `201`:
```json
{
@@ -83,141 +79,64 @@ API 失败时使用 RFC 9457 问题详情格式。缺失、无效或已撤销的
}
```
无效的 YAML 或未知的组织资源会返回 `422` 及字段问题。每次安装都是独立的请求;后面的失败不会撤销前面已成功的安装。见[从 CLI 部署](/docs/hub/configuration#deploy-from-the-cli)。
无效 YAML、未知集成或被拒绝的 Agent 设置会返回 `422` 及字段级错误详情。`paseo hub deploy --dry-run` 和 `paseo hub deploy` 会针对 `.paseo/triggers/*.yml` 调用这两个端点。
## 项目列表 {#project-list}
## Webhook 密钥 {#webhook-secrets}
`GET /api/v1/projects` 返回 bearer 凭据所属组织中的活动项目。`paseo hub projects` 以表格形式显示项目。使用 `--json` 时,它返回 `{ "origin": "...", "projects": [...] }`,因此即使结果为空,也会记录解析出的 Hub。
```json
{
"projects": [
{
"id": "00000000-0000-4000-8000-000000000000",
"slug": "my-project",
"name": "My project"
}
]
}
```
## 旧版配置校验 {#legacy-configuration-validation}
`POST /api/v1/configurations/validate` 接受与配置安装相同的 `projectSlug` 和完整的 `files` 文件包。它执行相同的编译和资源解析,但不会记录修订,也不会改变当前生效的配置。
成功时,Hub 返回 `200`:
```json
{
"projectSlug": "my-project",
"valid": true
}
```
`paseo hub deploy --project <slug> --dry-run` 会用与实际部署完全相同的、在本地解析出的请求体调用此端点。
## 旧版配置安装 {#legacy-configuration-install}
`configuration:install` 会校验提供的标准文件包,原样保存编写的文件,并激活一个新的修订。
```http
POST /api/v1/configurations/install
```
`POST /api/v1/triggers/webhook-secret`(`configuration:install`)为已保存的 `webhook.received` 触发器创建或轮换 Bearer 密钥。
请求体:
```json
{
"projectSlug": "my-project",
"files": [
{
"path": ".paseo/hub.yml",
"content": "environments:\n production:\n kind: daemon\n daemon: build-server\n cwd: /workspace\nagents:\n codex:\n provider: codex\n"
},
{
"path": ".paseo/workflows/deploy.yml",
"content": "name: deploy\non: manual.run\nmax_runtime: 2h\nfilters:\n from_users: [automation]\nsteps:\n - id: deploy\n environment: production\n max_runtime: 90m\n idle_timeout: 10m\n agent: codex\n prompt:\n - include: partials/safety.md\n"
},
{
"path": ".paseo/workflows/partials/safety.md",
"content": "Follow the safety checklist."
}
]
"triggerId": "00000000-0000-4000-8000-000000000001"
}
```
`projectSlug` 选择目标项目;bearer 凭据确定组织。`files` 包含 `.paseo/hub.yml`、每个直接位于目录下的 workflow `.yml`,以及每个被引用的 workflow 片段。Hub 会拒绝缺失、多余、重复、不安全或非标准的路径。
限制:
- 文件包:最多 100 个文件。
- 文件路径:最多 512 个字符。
- 文件内容:最多 1,000,000 个字符。
- 提示词片段:每个最多 1,000,000 字节,总计最多 5,000,000 字节。
成功时,Hub 返回 `201`:
成功后 Hub 返回 `200` 及 `Cache-Control: no-store`:
```json
{
"projectSlug": "my-project",
"versionId": "00000000-0000-4000-8000-000000000000",
"version": 3,
"active": true
"path": "/webhooks/wh_0123456789abcdef0123456789abcdef",
"secret": "whsec_..."
}
```
常见的响应有:请求体缺失或格式错误时返回 `400`,密钥所属组织中的项目不活动或未知时返回 `404`,YAML 无效或配置无效时返回 `422`。校验的问题详情包含字段问题。安装失败不会替换当前生效的修订。
每次调用都会立即替换旧密钥,并且新密钥仅显示一次。向 `/webhooks/wh_...` 发送投递的方式见[入站 webhook](/docs/hub/triggers/webhooks)。
示例:
## 手动运行派发 {#manual-run-dispatch}
```bash
curl --fail-with-body -sS -X POST "$PASEO_HUB_URL/api/v1/configurations/install" \
-H "Authorization: Bearer $PASEO_HUB_API_KEY" \
-H "Content-Type: application/json" \
--data @configuration-install.json
```
`paseo hub deploy -p <project>` 会用在本地发现的文件包调用这个旧版端点。在没有参数和环境变量凭据时,该命令使用与地址完全匹配的已保存登录。见[从 CLI 部署](/docs/hub/configuration#deploy-from-the-cli)。
## 发起手动运行 {#manual-run-dispatch}
`runs:dispatch` 为项目发起一个已配置的 `manual.run` 触发器。该触发器必须存在于当前生效的配置中,并且 `actor` 必须列在该触发器的 `filters.from_users` 白名单中。
```http
POST /api/v1/manual-runs
```
请求体:
`POST /api/v1/manual-runs`(`runs:dispatch`)启动一个已配置的 `manual.run` 触发器。`actor` 必须匹配该触发器的 `filters.from_users` 白名单(省略时为 `*`)。
```json
{
"projectSlug": "my-project",
"expectedVersionId": "00000000-0000-4000-8000-000000000000",
"trigger": "deploy",
"projectSlug": "default",
"trigger": "manual-task",
"actor": "automation",
"deliveryKey": "deploy-2026-08-04-001",
"deliveryKey": "manual-task-2026-09-09-001",
"input": "repo=project investigate the failed sync"
}
```
- `expectedVersionId` 是可选的。提供时,如果该修订已不再生效,Hub 会拒绝这次发起。
- `input` 与 Provider 消息使用的字符串相同:开头的 `key=value` 标记会被解析为声明的输入,其余部分成为 `${{ paseo.prompt }}`。
- `deliveryKey` 对每次发起都应唯一且稳定。Hub 用它进行持久化去重,但不保证恰好发起一次,也不保证重放之前的响应。
- `deliveryKey` 提供限定在组织和项目内的持久去重。
- `input` 接受以声明的 `inputs` 对应的 `key=value` 头部开头,后接提示词文本。
成功时,Hub 返回 `200`:
派发独立触发器时,请省略 `expectedVersionId`。如果传入安装触发器时返回的 `revisionId`,即使触发器没有变化,Hub 也会返回 HTTP `409`(`configuration_changed`)。
对于旧版项目配置包,`expectedVersionId` 为可选项。将它设为当前生效的项目配置修订 ID,配置变更后 Hub 就会拒绝派发。
成功后 Hub 返回 `200`:
```json
{
"deliveryKey": "deploy-2026-08-04-001",
"deliveryKey": "manual-task-2026-09-09-001",
"providerEventReceiptId": "00000000-0000-4000-8000-000000000000",
"triggerRunId": "00000000-0000-4000-8000-000000000000",
"configuredTriggerName": "deploy",
"configuredTriggerName": "manual-task",
"workflowStatus": "running"
}
```
常见的响应有:请求无效时返回 `400`,触发器不允许该 actor 时返回 `403`,项目、配置或触发器未知时返回 `404`,daemon 离线、预期的配置已不是当前配置或发起冲突时返回 `409`。它们都使用上面的问题详情格式。
示例:
```bash
@@ -225,36 +144,17 @@ curl --fail-with-body -sS -X POST "$PASEO_HUB_URL/api/v1/manual-runs" \
-H "Authorization: Bearer $PASEO_HUB_API_KEY" \
-H "Content-Type: application/json" \
--data '{
"projectSlug": "my-project",
"trigger": "deploy",
"projectSlug": "default",
"trigger": "manual-task",
"actor": "automation",
"deliveryKey": "deploy-2026-08-04-001",
"input": "repo=project investigate the failed sync"
"deliveryKey": "manual-task-2026-09-09-001",
"input": "investigate the failed sync"
}'
```
输入类型、默认值、可选值、被拒绝的输入以及手动调用示例,见 [Hub workflow](/docs/hub/workflows)。
## Daemon 注册 {#daemon-enrollment}
## 注册 daemon {#daemon-enrollment}
`daemons:enroll` 为 daemon 签发一个短期有效的注册令牌。这个令牌由 API 密钥签发;它不是 daemon 的长期凭据,也不得当作长期凭据使用。
```http
POST /api/v1/daemons/enrollment-tokens
```
不需要请求体。成功时,Hub 返回 `201`:
```json
{
"token": "short-lived-enrollment-token",
"expiresAt": "2026-08-04T12:10:00.000Z"
}
```
令牌在 10 分钟后过期,并在 daemon 注册时被消耗。
`paseo hub connect [origin]` 会使用 `--api-key`、`PASEO_HUB_API_KEY` 或匹配的已保存登录执行此请求,然后把这个一次性令牌传给 daemon 的注册操作。daemon 会生成并保存它自己的关系凭据。
`POST /api/v1/daemons/enrollment-tokens`(`daemons:enroll`)签发一个 10 分钟后过期的一次性注册令牌。不需要请求体。
```bash
curl --fail-with-body -sS -X POST \
@@ -262,12 +162,17 @@ curl --fail-with-body -sS -X POST \
-H "Authorization: Bearer $PASEO_HUB_API_KEY"
```
直接使用 API 的调用方可以把返回的令牌传给 daemon 注册协议。Paseo CLI 有意不接受原始注册令牌;`connect` 负责完整的、经过身份验证的单一交换流程。
响应(`201`):
注册令牌不能重复使用。撤销 API 密钥会立即拒绝之后的 API 请求,并使该密钥签发的所有未消耗的注册令牌过期。撤销与签发之间的竞争会在新令牌被保存之前由 Hub 解决。
```json
{
"token": "short-lived-enrollment-token",
"expiresAt": "2026-09-09T12:10:00.000Z"
}
```
## 密钥、权限范围和审计信息 {#keys-scopes-and-audit-information}
`paseo hub connect [origin]` 会自动调用此端点,并用令牌换取 daemon 自己的长期关系凭据。撤销 API 密钥会立即阻止新的 API 调用,并使该密钥签发的未消耗注册令牌失效。
完整的 API 密钥只在创建后立即显示一次。请把它保存到你的部署所用的密钥管理器中;Hub 不会再次显示它。控制台只保留密钥的前缀,并显示它所选的权限范围、创建时间、最后使用时间和状态。
## 密钥与审计记录 {#keys-and-audit-trails}
密钥在一次有权限范围的 API 操作中成功通过身份验证后,Hub 会更新 `last used`。API 操作会在 Hub 的审计记录中保留密钥归属,因此配置修订、手动发起和 daemon 注册令牌都可以追溯到创建它们的组织密钥。
Hub 仅在创建时显示一次 API 密钥内容。控制台只保留密钥前缀、权限范围、创建时间、最近使用时间和撤销状态。Hub 会在触发器安装、webhook 轮换、手动派发和 daemon 注册令牌中保留密钥归属记录。
+41 -42
View File
@@ -1,6 +1,6 @@
---
title: How Hub works
description: How a provider event reaches a workflow and a Paseo daemon.
description: How events, schedules, and webhooks match a trigger and start an agent on your Paseo daemon.
nav: How it works
order: 62
category: Hub
@@ -8,61 +8,60 @@ category: Hub
# How Hub works
Hub connects the places where requests arrive to the machines where your agents run.
Hub connects external events, schedules, and webhooks to coding agents running on your Paseo daemons.
```text
GitHub / Slack / Discord / manual request
↓
Hub
matches a project trigger
↓
workflow
runs ordered agent steps
↓
Paseo daemon
starts the agent
GitHub / Linear / Slack / Discord / Schedule / Webhook
│
▼
Hub
verifies input and matches triggers
│
▼
Paseo daemon
starts or continues an agent
```
## The pieces
## Core concepts
- A **connection** lets Hub receive events from GitHub, Slack, or Discord.
- A **daemon** is a registered machine running the Paseo daemon.
- A **project** groups one configuration with the connections and daemons it uses.
- An **environment** names where a workflow step runs: a daemon, its working directory, and an optional worktree.
- A **trigger** says which provider event can start a workflow and which events are allowed through.
- A **workflow** is the ordered set of steps that runs after a trigger matches.
- A **step** starts one agent execution, with its own prompt, agent selection, credentials, reply capabilities, and limits.
The configuration lives in `.paseo/hub.yml` plus convention-discovered `.paseo/workflows/*.yml` files when the project uses a GitHub source. A project has one active configuration revision at a time.
- An **app** is the provider application configured for a self-hosted Hub under **Apps** (GitHub App, Linear OAuth app, Slack app, or Discord app). Hosted Hub operates its own apps.
- An **integration** is a workspace, account, or server connected to your Hub organization under **Integrations**. Each connected account has a unique connection slug, such as `acme-github` or `acme-slack`, that triggers reference.
- A **daemon** is a machine running the Paseo daemon and enrolled in your Hub organization under **Daemons**. Daemons accept agent launches only after you grant `hub.execute` from that machine.
- A **trigger** is one self-contained rule that maps an event, schedule, or webhook to a target daemon, working directory, agent configuration, prompt, and optional tools or outputs.
- **Activity** records every accepted delivery, routing decision, execution status, reply, and error across the organization.
## From event to agent
1. A provider sends an event to Hub. GitHub and Slack use webhooks; Discord uses its gateway connection; manual runs use the Hub API.
2. Hub verifies the provider event and identifies its project resource, such as a repository, workspace, or guild.
3. Hub evaluates triggers and their filters, including the required `from_users` allowlist.
4. A matching trigger creates a workflow run from the active configuration revision.
5. The workflow evaluates its next step. A false `if` condition skips that step; a true condition starts it on the configured daemon.
6. The daemon starts the agent and Hub records its replies, structured output, status, and completion.
7. The next step sees the completed step's output. When no steps remain, the workflow run is complete.
1. An event arrives via HTTPS webhooks (GitHub, Linear, Slack Webhooks, or inbound webhooks), an outbound connection (Slack Socket Mode or Discord gateway), or Hub's schedule clock.
2. Hub verifies the sender or signature and looks up matching enabled triggers.
3. For external provider events, Hub evaluates the trigger's connection, resource filters, and sender allowlist (`from_users`).
4. For each matching trigger, Hub creates a run and sends the launch intent to the target daemon over the same RPC protocol used by the Paseo app and CLI.
5. By default, events on the same Slack thread, Discord thread, GitHub issue or pull request, or Linear issue continue the existing agent session rather than starting a new one.
6. The agent runs on your machine with the Hub MCP server attached. It calls `reply` to answer the conversation, calls any granted integration tools, and calls `finish_execution` when complete.
Complete configurations are in [Workflows](/docs/hub/workflows).
## Authoring and validation
## Activation
You can create and edit triggers in two ways:
When Hub syncs the bundle, it validates every source file and resolves its references:
- In the Hub dashboard under **Triggers**, using the visual form or the YAML editor.
- As `.paseo/triggers/*.yml` files in your repository, deployed with `paseo hub deploy`.
- `filters.repo`, `filters.workspace`, and `filters.guild` must name resources available through the organization's connections.
- `environment.daemon` must match a registered daemon's friendly slug.
- Step ids, expressions, input filters, output schemas, and durations must be valid.
- Every finite environment or named-agent result must exist and validate.
- Prompt partials must resolve below `.paseo/workflows/partials/` at the exact commit.
Both paths use the same YAML schema. When you save or deploy, Hub validates the YAML and looks up the connections for event routing and the target daemon.
If activation fails, Hub keeps the previous active revision. The Configuration tab shows the failed sync and its validation error; Activity continues to reflect the last active revision.
You can save dashboard edits while the daemon is offline if the target and agent settings stay the same. CLI deploys and direct API installs always require a connected target daemon. See [trigger validation](/docs/hub/triggers#saving-checks-the-agent-against-the-daemon).
Hub resolves `run.github.connection` when it launches the run. If the connection is unavailable or GitHub rejects the token request, the launch fails. See [GitHub access for agents](/docs/hub/github).
## Open in Paseo links
When Hub has a public HTTPS origin and a run has a recorded daemon agent, Hub appends an **Open in Paseo** link to conversation replies on GitHub, Linear, Slack, and Discord.
Clicking the link checks that the visitor is a signed-in member of that Hub organization before offering to open the exact agent in Paseo, view the execution in Hub, or install Paseo. Signed-out visitors and users outside the organization receive no run details.
Agents with scoped posting tools (`run.tools.slack` or `run.tools.discord`) also receive the same URL in their request context so digests and reports can link back to the run.
## Security boundaries
Triggers require a non-empty `from_users` allowlist for externally sourced events. Protect the configuration repository because anyone who can change the active configuration can choose which connections, daemons, and agent capabilities a project uses.
Hub verifies inbound requests, enforces sender allowlists, mints scoped GitHub tokens, and authorizes every Hub MCP tool call on the server. It does not sandbox the coding agent process on your machine.
These controls do not sandbox the agent or make input safe. See [Hub security](/docs/hub/security) for the host boundary, provider-native policy, and defense-in-depth guidance.
GitHub credentials are never implied by the trigger. A step holds GitHub authority only when it declares a [`github` block](/docs/hub/github), whatever started the run.
Protect access to your Hub organization and any repository that deploys `.paseo/triggers/*.yml`. Read [Hub security](/docs/hub/security) before widening allowlists or granting repository write permissions.
+43 -44
View File
@@ -1,66 +1,65 @@
---
title: Hub 工作原理
description: Provider 事件如何到达 workflow 和 Paseo daemon。
title: Hub 的工作原理
description: 事件、定时任务和 webhook 如何匹配触发器,并在你的 Paseo daemon 上启动 Agent。
nav: 工作原理
---
# Hub 工作原理 {#how-hub-works}
# Hub 的工作原理 {#how-hub-works}
Hub 把请求到达的地方与运行 Agent 的机器连接起来。
Hub 将外部事件、定时任务和 webhook 连接到在你 Paseo daemon 上运行的编程 Agent。
```text
GitHub / Slack / Discord / manual request
↓
Hub
matches a project trigger
↓
workflow
runs ordered agent steps
↓
Paseo daemon
starts the agent
GitHub / Linear / Slack / Discord / Schedule / Webhook
│
▼
Hub
verifies input and matches triggers
│
▼
Paseo daemon
starts or continues an agent
```
## 组成部分 {#the-pieces}
## 核心概念 {#core-concepts}
- **连接**让 Hub 接收来自 GitHub、Slack 或 Discord 的事件。
- **daemon** 是一台运行 Paseo daemon 的已注册机器。
- **项目**把一份配置与它使用的连接和 daemon 组织在一起。
- **环境**指定 workflow step 在哪里运行:一个 daemon、它的工作目录,以及可选的 worktree。
- **触发器**说明哪个 Provider 事件可以启动 workflow,以及允许哪些事件通过。
- **workflow** 是触发器匹配后运行的一组有序 step。
- **step** 启动一次 Agent 执行,有自己的提示词、Agent 选择、凭据、回复能力和限制。
当项目使用 GitHub 来源时,配置位于 `.paseo/hub.yml` 以及按约定发现的 `.paseo/workflows/*.yml` 文件中。一个项目同一时间只有一个生效的配置版本。
- **App** 是在自托管 Hub 的 **Apps** 下配置的 Provider 应用(GitHub App、Linear OAuth 应用、Slack 应用或 Discord 应用)。托管 Hub 运行自己的应用。
- **Integration** 是在 **Integrations** 下连接到你 Hub 组织的工作区、账号或服务器。每个已连接的账号都有唯一的连接 slug(例如 `acme-github` 或 `acme-slack`),供触发器引用。
- **Daemon** 是运行 Paseo daemon 并注册到你 Hub 组织 **Daemons** 下的机器。只有在机器上授予 `hub.execute` 后,daemon 才会接受 Agent 启动请求。
- **Trigger** 是一条自包含规则,将事件、定时任务或 webhook 映射到目标 daemon、工作目录、Agent 配置、提示词,以及可选的工具或输出。
- **Activity** 记录组织内每一次已接受的投递、路由决策、执行状态、回复和错误。
## 从事件到 Agent {#from-event-to-agent}
1. Provider 向 Hub 发送事件。GitHub 和 Slack 使用 webhook;Discord 使用它的 gateway 连接;手动运行使用 Hub API。
2. Hub 验证 Provider 事件,并识别它对应的项目资源,例如仓库、工作区或服务器。
3. Hub 评估触发器及其过滤器,包括必填的 `from_users` 允许列表。
4. 匹配的触发器根据当前生效的配置版本创建一次 workflow 运行。
5. workflow 评估下一个 step。`if` 条件为假时跳过该 step;为真时在配置的 daemon 上启动它。
6. daemon 启动 Agent,Hub 记录它的回复、结构化输出、状态和完成情况。
7. 下一个 step 可以看到已完成 step 的输出。没有剩余 step 时,workflow 运行完成。
1. 事件通过 HTTPS webhook(GitHub、Linear、Slack Webhooks 或入站 webhook)、出站连接(Slack Socket Mode 或 Discord gateway)或 Hub 定时时钟到达。
2. Hub 验证发送者或签名,并查找匹配的已启用触发器。
3. 对于外部 Provider 事件,Hub 会评估触发器的连接、资源过滤条件和发送者白名单(`from_users`)。
4. 对每个匹配的触发器,Hub 创建一次运行,并通过 Paseo 应用和 CLI 使用的同一套 RPC 协议向目标 daemon 发送启动意图。
5. 默认情况下,同一个 Slack 讨论串、Discord 讨论串、GitHub issue 或 Pull Request,以及同一个 Linear issue 上的事件会继续现有 Agent 会话,而不是启动新的 Agent。
6. Agent 在你的机器上运行并挂载 Hub MCP 服务器。它调用 `reply` 回复对话,调用已授予的集成工具,并在完成后调用 `finish_execution`。
完整的配置示例见 [Workflow](/docs/hub/workflows)。
## 编写与校验 {#authoring-and-validation}
## 激活 {#activation}
你可以通过两种方式创建和编辑触发器:
Hub 同步配置包时,会校验每个源文件并解析其中的引用:
- 在 Hub 控制台的 **Triggers** 页面使用可视化表单或 YAML 编辑器。
- 在仓库中保存 `.paseo/triggers/*.yml` 文件,并通过 `paseo hub deploy` 部署。
- `filters.repo`、`filters.workspace` 和 `filters.guild` 必须指向通过组织的连接可以访问的资源。
- `environment.daemon` 必须匹配一个已注册 daemon 的友好 slug。
- step id、表达式、输入过滤器、输出 schema 和时长必须有效。
- 每个有限的环境或命名 Agent 结果都必须存在并通过校验。
- 提示词片段必须能在该提交中 `.paseo/workflows/partials/` 下解析到。
两种方式使用相同的 YAML 结构。保存或部署触发器时,Hub 会校验 YAML,并查找用于事件路由的连接和目标 daemon。
如果激活失败,Hub 会保留之前生效的版本。Configuration 标签页会显示失败的同步及其校验错误;Activity 继续反映上一个生效的版本。
只要目标和 Agent 设置不变,daemon 离线时也能在控制台保存修改。通过 CLI 部署或直接通过 API 安装时,目标 daemon 必须连接到 Hub。请参阅[触发器校验](/docs/hub/triggers#saving-checks-the-agent-against-the-daemon)。
Hub 在启动运行时解析 `run.github.connection`。如果连接不可用或 GitHub 拒绝签发令牌,运行就会启动失败。请参阅 [Agent 的 GitHub 访问权限](/docs/hub/github)。
## Open in Paseo 链接 {#open-in-paseo-links}
当 Hub 配置了公开 HTTPS 地址且运行记录了 daemon Agent 时,Hub 会在 GitHub、Linear、Slack 和 Discord 的对话回复中附带 **Open in Paseo** 链接。
点击链接时,Hub 会先验证访问者是否为该 Hub 组织的已登录成员,然后提供在 Paseo 中打开对应 Agent、在 Hub 中查看运行记录或安装 Paseo 的入口。未登录的访客和非组织成员不会看到任何运行数据。
拥有受控发送工具(`run.tools.slack` 或 `run.tools.discord`)的 Agent 也会在请求上下文中收到同一个 URL,方便摘要和报告主动链接回此次运行。
## 安全边界 {#security-boundaries}
对于来自外部的事件,触发器要求 `from_users` 允许列表不能为空。请保护好配置仓库,因为任何能够修改生效配置的人,都可以决定项目使用哪些连接、daemon 和 Agent 能力。
Hub 负责验证入站请求、执行发送者白名单、签发受控 GitHub 令牌,并在服务端对每次 Hub MCP 工具调用做鉴权。它不会在你机器上为编程 Agent 进程提供沙箱隔离。
这些控制措施不会把 Agent 放进沙箱,也不会让输入变得安全。主机边界、Provider 原生策略和纵深防御方面的指导见 [Hub 安全](/docs/hub/security)。
触发器从不隐含 GitHub 凭据。无论运行由什么启动,只有当 step 声明了 [`github` 块](/docs/hub/github)时,它才拥有 GitHub 权限。
请保护你的 Hub 组织访问权限,以及任何用于部署 `.paseo/triggers/*.yml` 的仓库。在扩大白名单或授予仓库写入权限之前,请先阅读 [Hub 安全](/docs/hub/security)。
-283
View File
@@ -1,283 +0,0 @@
---
title: Hub configuration reference
description: Canonical Hub resource, workflow, agent, expression, and prompt fields.
nav: Configuration reference
order: 71
category: Hub
---
# Hub configuration reference
Hub accepts YAML in this layout:
```text
.paseo/
├── hub.yml
└── workflows/
├── <workflow>.yml
└── partials/
└── <partial>.md
```
Only direct `.yml` children of `.paseo/workflows/` are workflows. Each file contains one trigger and its ordered steps. There is no manifest, `includes`, `uses`, reusable step, workflow call, or inheritance.
## `hub.yml`
`.paseo/hub.yml` contains named project resources. Names are map keys and are not repeated inside each object.
```yaml
environments:
paseo:
kind: daemon
daemon: laptop
cwd: /Users/you/code/paseo
hub:
kind: daemon
daemon: devbox
cwd: /workspace/hub
agents:
codex-safe:
provider: codex
model: gpt-5.5
thinkingOptionId: xhigh
options:
sandbox_workspace_write:
writable_roots: [/var/cache/npm]
network_access: false
claude:
provider: claude
mode: bypassPermissions
```
The only top-level keys are `environments` and `agents`. A `triggers` key is rejected with a migration error.
### Environments
| Field | Required | Notes |
| ---------- | ----------- | ------------------------------------------------------------------------------ |
| `kind` | yes | `daemon`, `fly`, or `docker`; workflow steps must select a daemon environment. |
| `daemon` | daemon only | Registered daemon slug, resolved when the revision activates. |
| `cwd` | daemon only | Absolute working directory on the daemon. |
| `image` | fly/docker | Image name. |
| `worktree` | no | `branch-off`, `checkout-branch`, or `checkout-pr` target. |
For `worktree`, use `newBranch` and optional `base` with `branch-off`, `branch` with `checkout-branch`, or positive `prNumber` with `checkout-pr`.
```yaml
environments:
review:
kind: daemon
daemon: build-server
cwd: /workspace/project
worktree:
mode: branch-off
newBranch: trigger-${{ paseo.execution.id }}
base: origin/main
```
`newBranch` is a branch-name string. Embed `${{ paseo.execution.id }}`, which renders the execution's UUID, so every execution branches off `base` on its own branch and keeps it when Hub retries or recovers that execution.
One execution is one step run, so two steps selecting the same environment get separate branches.
`${{ paseo.execution.id }}` is the only expression `newBranch` accepts. `paseo.prompt`, `paseo.context`, `paseo.inputs.*`, `values.*`, `steps.<id>.outputs.*`, and provider event fields are unavailable here, and each one fails bundle activation at the authored field, such as `.paseo/hub.yml.environments.review.worktree.newBranch`.
`${{ paseo.execution.id }}` fails activation the same way anywhere else in a bundle. `branch` and `prNumber` take literal values.
An environment is a complete named object. A step selects its name; objects are not inherited, merged, or partially overridden.
### Named agents
Each agent is one complete provider configuration:
| Field | Required | Notes |
| ------------------ | -------- | ---------------------------------------------------------------------- |
| `provider` | yes | Provider ID. Hub runs unattended, so `claude`, `codex`, or `opencode`. |
| `model` | no | Provider model ID. |
| `mode` | no | Paseo mode ID. |
| `thinkingOptionId` | no | Provider thinking option. |
| `options` | no | JSON-safe provider-native options, preserving names and nesting. |
A named selection preserves the complete object, including structured options. Named agents have no parent, patch, or per-step override.
Hub passes `model`, `mode`, `thinkingOptionId`, and `options` to the Paseo daemon without renaming or flattening provider fields. The selected daemon validates them against its current provider schema when the trigger is saved or deployed, so a value it does not offer is refused then rather than at the first run; Hub does not translate provider-native options. See [Saving checks the agent against the daemon](/docs/hub/triggers#saving-checks-the-agent-against-the-daemon).
## Workflow files
`.paseo/workflows/review.yml`:
```yaml
name: review
on: manual.run
max_runtime: 2h
filters:
from_users: [automation]
inputs:
repo:
type: string
required: true
choices: [paseo, hub]
steps:
- id: inspect
environment: ${{ paseo.inputs.repo }}
max_runtime: 30m
idle_timeout: 5m
agent: codex-safe
prompt:
- text: ${{ paseo.prompt }}
```
| Field | Required | Notes |
| ------------- | -------- | --------------------------------------------------------- |
| `name` | yes | Workflow name, unique across the bundle. |
| `on` | yes | Provider event such as `manual.run` or `discord.mention`. |
| `max_runtime` | yes | Hard limit for the complete run, up to 24h. |
| `filters` | yes | Provider resource filters and the sender allowlist. |
| `inputs` | no | Typed invocation headers. |
| `values` | no | Named expressions. |
| `steps` | yes | One or more ordered inline steps. |
### GitHub events and filters
Use one of these semantic event names for new GitHub workflows:
| `on` | Matches |
| -------------------------------------- | ------------------------------------------------------------------------- |
| `github.issue_created` | An `issues` delivery whose action is `opened`. |
| `github.pull_request_created` | A `pull_request` delivery whose action is `opened`. |
| `github.pull_request_ready_for_review` | A draft pull request is marked ready for review. |
| `github.issue_comment_created` | An `issue_comment` delivery whose action is `created`, on an issue. |
| `github.pull_request_comment_created` | An `issue_comment` delivery whose action is `created`, on a pull request. |
| `github.issue_label_added` | An `issues` delivery whose action is `labeled`. |
| `github.pull_request_label_added` | A `pull_request` delivery whose action is `labeled`. |
Existing configurations may continue to use `github.issues`, `github.issue_comment`, `github.pull_request_review`, `github.pull_request_review_comment`, and `github.push`. These legacy events retain their existing behavior.
`filters` supports these GitHub fields. `from_users` must be non-empty for every externally sourced workflow. All supplied filters compose with AND.
| Field | Type | Applies to | Meaning |
| ------------ | ----------------------------------- | ------------------------------------------------------------- | ------------------------------------------------------------------------------- |
| `from_users` | non-empty list of strings | all GitHub events | GitHub logins allowed to start the workflow. |
| `repo` | non-empty string | all GitHub events | Repository in `owner/name` form. |
| `connection` | string | all GitHub events | GitHub connection slug. |
| `contains` | string | issue, pull-request, and comment events | Substring in the issue or pull-request title plus body, or in the comment body. |
| `pattern` | string | issue, pull-request, and comment events | Start of that same text. |
| `label` | non-empty string | `github.issue_label_added`, `github.pull_request_label_added` | The label added by the delivery. |
| `labels` | non-empty list of non-empty strings | issue, pull-request, and comment events | Every listed label must be currently present on the issue or pull request. |
`label` and `labels` match GitHub labels case-insensitively. `label` checks the one changed label; `labels` checks the full current label set and requires every entry. For example, `labels: [bug, backend]` requires both `bug` and `backend`.
Use `label` only with a label-added event. It has no match on other events. Use `labels` to require the item state, including when a comment starts the workflow.
See [GitHub triggers](/docs/hub/triggers/github) for complete triage, pull-request review, and ready-for-agent workflows.
### Inputs and values
Inputs have `type: string | number | boolean`, plus optional `required`, `default`, and `choices`. `required` and `default` cannot be combined. Finite `choices` are required when an input can choose authority such as an environment or named agent.
Values bind expressions:
```yaml
values:
selected_environment: ${{ steps.classify.outputs.environment }}
selected_agent: ${{ steps.classify.outputs.agent }}
```
Expressions may read declared `paseo.inputs`, earlier `steps.<id>.outputs`, and `values`. The grammar supports paths, JSON literals, parentheses, `!`, `==`, `!=`, `&&`, `||`, and `??`.
An environment or dynamic named-agent expression must have a finite set of possible string results at activation. Every result must name a configured resource. Runtime selection never falls back to another environment or agent.
### Steps
| Field | Required | Notes |
| ----------------- | -------- | -------------------------------------------------------------------------------------------------------------------- |
| `id` | yes | Unique within the workflow. |
| `environment` | yes | Literal environment name or finite expression resolving to one. |
| `max_runtime` | yes | Step hard limit. |
| `idle_timeout` | yes | Idle limit no longer than `max_runtime`. |
| `startup_timeout` | no | Step startup waiting budget. See [startup timeout](/docs/hub/configuration#startup-timeout) for defaults and limits. |
| `agent` | yes | Named agent, finite expression selecting a named agent, or complete static inline agent. |
| `prompt` | yes | Ordered `text` and `include` blocks. |
| `if` | no | Expression deciding whether the step runs. |
| `env` | no | Environment variables from connection values. |
| `output.schema` | no | JSON Schema for structured step output. |
| `allow_outputs` | no | Provider output capabilities with optional `max` and `required`. |
| `auto_archive` | no | Archive the agent after the step ends. |
| `github` | no | Explicit GitHub authority for this step. |
An inline agent is static and complete:
```yaml
agent:
provider: codex
model: gpt-5.5
options:
approval_policy: never
sandbox_mode: read-only
```
An expression-valued `agent` selects a named agent. Dynamic provider fields inside an inline object are rejected.
### Prompt semantics
```yaml
prompt:
- include: partials/review.md
- text: |
<user-prompt>
${{ paseo.prompt }}
</user-prompt>
```
`${{ paseo.prompt }}` is the normalized request after the provider marker and declared leading `key=value` inputs are removed. It is not rewritten or augmented with event context.
`${{ paseo.context }}` opts that step into provider context materialization and renders the result as JSON in the prompt. It is available only in prompt text. Hub does not inject it unless the workflow authors that expression.
Includes resolve relative to `.paseo/workflows/`, so shared partials use `partials/<name>.md`. Missing files, absolute or traversing paths, symlinks, content mismatches, and files outside the partial tree are rejected.
### Output capabilities
Authority stays on the step that uses it:
```yaml
allow_outputs:
- type: discord.reply
max: 1
required: true
```
Slack workflows use `slack.reply`; Discord workflows use `discord.reply`. The declaration grants `hub.reply`, and the prompt must tell the agent to call it. GitHub has no reply output; use an explicit [`github` block](/docs/hub/github).
Every step receives `hub.finish_execution`. The prompt must tell the agent when to call it; Hub does not append completion or reply instructions. If `output.schema` is present, `hub.finish_execution` requires an `output` value that matches the schema. If an `allow_outputs` entry is `required: true`, the agent must emit that output before finishing. `max` defaults to `1`.
## Migrating a monolithic file
Keep `environments` in `hub.yml`, convert the environment list to a named map, and move each former trigger into its own `.paseo/workflows/<name>.yml` file. Move shared prompt files to `.paseo/workflows/partials/`. Define complete named agent configurations under `agents` and replace dynamic provider fields with finite named-agent selection.
Hub does not read TOML or a monolithic `triggers` section, and the CLI does not rewrite either format.
See [Workflows](/docs/hub/workflows) for complete routing examples.
## Agent continuation
Self-contained dashboard trigger documents accept `run.continuation`:
| Value | Behavior |
| -------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| `{mode: conversation}` | Default. Reuse the project's agent for the event's conversation; create a new agent when the event has no conversation. |
| `{mode: key, key: "support-${{ paseo.inputs.ticket }}"}` | Reuse the project's agent for the evaluated custom key. |
| `{mode: new}` | Create a new agent for each arrival. |
Keys use the existing expression syntax and must resolve to a non-empty string of at most 512 characters. Custom keys and provider conversation identities occupy separate namespaces. The same key in different projects does not share an agent.
An existing session keeps its daemon, agent configuration, target, environment, and tool contracts. Changing those settings for the same key fails with an explanation; choose a different key or **New agent**. Prompts and output destinations belong to each arrival and may change. A worktree branch is chosen when the session is first created and reused on later arrivals.
A follow-up steers the active agent without extending its runtime deadline or credential expiry. With a `run.github` grant or connection token in `run.env`, follow-ups share the active agent’s credentials. Once all requests finish, Hub revokes leased tokens; the next arrival starts a new agent with fresh credentials. Agents without temporary credentials can be reused after completion.
### Upgrading
Upgrade the connected Paseo daemons before enabling the new Hub version. Hub requires the daemon's ordinary agent RPC and request receipt capabilities; an older host produces an actionable dispatch error.
Hub's database migration adds sessions and nullable execution associations. Existing executions retain their saved launch contract and execution-specific MCP endpoint until they finish. New arrivals for existing self-contained trigger documents use the conversation default. Historical agents are not backfilled into sessions.
Legacy multi-step workflow bundles keep their existing behavior. Converting one to a self-contained trigger writes `mode: new` explicitly; change it in the editor when ready to reuse agents.
@@ -1,281 +0,0 @@
---
title: Hub 配置参考
description: Hub 资源、workflow、Agent、表达式和提示词字段的标准参考。
nav: 配置参考
---
# Hub 配置参考 {#hub-configuration-reference}
Hub 接受以下结构的 YAML:
```text
.paseo/
├── hub.yml
└── workflows/
├── <workflow>.yml
└── partials/
└── <partial>.md
```
只有 `.paseo/workflows/` 下直接的 `.yml` 子文件才是 workflow。每个文件包含一个触发器及其有序的 step。没有 manifest、`includes`、`uses`、可复用的 step、workflow 调用或继承。
## `hub.yml` {#hubyml}
`.paseo/hub.yml` 包含具名的项目资源。名称是映射的键,不会在每个对象内部重复。
```yaml
environments:
paseo:
kind: daemon
daemon: laptop
cwd: /Users/you/code/paseo
hub:
kind: daemon
daemon: devbox
cwd: /workspace/hub
agents:
codex-safe:
provider: codex
model: gpt-5.5
thinkingOptionId: xhigh
options:
sandbox_workspace_write:
writable_roots: [/var/cache/npm]
network_access: false
claude:
provider: claude
mode: bypassPermissions
```
顶层只有 `environments` 和 `agents` 两个键。`triggers` 键会被拒绝,并给出迁移错误。
### 环境 {#environments}
| 字段 | 是否必填 | 说明 |
| ---------- | ---------- | -------------------------------------------------------------------- |
| `kind` | 是 | `daemon`、`fly` 或 `docker`;workflow 的 step 必须选择 daemon 环境。 |
| `daemon` | 仅 daemon | 已注册的 daemon slug,在修订激活时解析。 |
| `cwd` | 仅 daemon | daemon 上的绝对工作目录。 |
| `image` | fly/docker | 镜像名称。 |
| `worktree` | 否 | `branch-off`、`checkout-branch` 或 `checkout-pr` 目标。 |
对于 `worktree`,`branch-off` 使用 `newBranch` 和可选的 `base`,`checkout-branch` 使用 `branch`,`checkout-pr` 使用正整数 `prNumber`。
```yaml
environments:
review:
kind: daemon
daemon: build-server
cwd: /workspace/project
worktree:
mode: branch-off
newBranch: trigger-${{ paseo.execution.id }}
base: origin/main
```
`newBranch` 是一个分支名字符串。在其中嵌入 `${{ paseo.execution.id }}`,它会渲染为该次执行的 UUID,这样每次执行都会从 `base` 分出自己的分支,并在 Hub 重试或恢复该执行时保留这个分支。
一次执行就是一次 step 运行,因此选择同一环境的两个 step 会得到各自独立的分支。
`${{ paseo.execution.id }}` 是 `newBranch` 唯一接受的表达式。`paseo.prompt`、`paseo.context`、`paseo.inputs.*`、`values.*`、`steps.<id>.outputs.*` 以及 Provider 事件字段在这里都不可用,任何一个都会在编写它的字段处导致文件包激活失败,例如 `.paseo/hub.yml.environments.review.worktree.newBranch`。
`${{ paseo.execution.id }}` 出现在文件包中其他任何位置时,同样会导致激活失败。`branch` 和 `prNumber` 只接受字面值。
环境是一个完整的具名对象。step 选择它的名称;对象不会被继承、合并或部分覆盖。
### 具名 Agent {#named-agents}
每个 Agent 是一份完整的 Provider 配置:
| 字段 | 是否必填 | 说明 |
| ------------------ | -------- | --------------------------------------------------------------------------------- |
| `provider` | 是 | Provider ID。Hub 在无人值守的情况下运行,因此为 `claude`、`codex` 或 `opencode`。 |
| `model` | 否 | Provider 的模型 ID。 |
| `mode` | 否 | Paseo 模式 ID。 |
| `thinkingOptionId` | 否 | Provider 的思考选项。 |
| `options` | 否 | 可安全序列化为 JSON 的 Provider 原生选项,保留名称和嵌套结构。 |
具名选择会保留完整的对象,包括结构化的选项。具名 Agent 没有父级、补丁或按 step 的覆盖。
Hub 把 `model`、`mode`、`thinkingOptionId` 和 `options` 传给 Paseo daemon,不会重命名或展平 Provider 字段。保存或部署触发器时,所选的 daemon 会按它当前的 Provider schema 校验这些值,因此它不提供的值会在那时被拒绝,而不是等到第一次运行;Hub 不会转换 Provider 原生选项。见[保存时会对照 daemon 检查 Agent](/docs/hub/triggers#saving-checks-the-agent-against-the-daemon)。
## workflow 文件 {#workflow-files}
`.paseo/workflows/review.yml`:
```yaml
name: review
on: manual.run
max_runtime: 2h
filters:
from_users: [automation]
inputs:
repo:
type: string
required: true
choices: [paseo, hub]
steps:
- id: inspect
environment: ${{ paseo.inputs.repo }}
max_runtime: 30m
idle_timeout: 5m
agent: codex-safe
prompt:
- text: ${{ paseo.prompt }}
```
| 字段 | 是否必填 | 说明 |
| ------------- | -------- | ------------------------------------------------------- |
| `name` | 是 | workflow 名称,在整个文件包中唯一。 |
| `on` | 是 | Provider 事件,例如 `manual.run` 或 `discord.mention`。 |
| `max_runtime` | 是 | 整次运行的硬性时间上限,最多 24h。 |
| `filters` | 是 | Provider 资源过滤条件和发送者白名单。 |
| `inputs` | 否 | 带类型的调用头部参数。 |
| `values` | 否 | 具名表达式。 |
| `steps` | 是 | 一个或多个有序的内联 step。 |
### GitHub 事件和过滤条件 {#github-events-and-filters}
新的 GitHub workflow 请使用以下语义化事件名之一:
| `on` | 匹配 |
| -------------------------------------- | ----------------------------------------------------------------- |
| `github.issue_created` | action 为 `opened` 的 `issues` 投递。 |
| `github.pull_request_created` | action 为 `opened` 的 `pull_request` 投递。 |
| `github.pull_request_ready_for_review` | 草稿 PR 被标记为可审查。 |
| `github.issue_comment_created` | 在 issue 上、action 为 `created` 的 `issue_comment` 投递。 |
| `github.pull_request_comment_created` | 在 Pull Request 上、action 为 `created` 的 `issue_comment` 投递。 |
| `github.issue_label_added` | action 为 `labeled` 的 `issues` 投递。 |
| `github.pull_request_label_added` | action 为 `labeled` 的 `pull_request` 投递。 |
已有的配置可以继续使用 `github.issues`、`github.issue_comment`、`github.pull_request_review`、`github.pull_request_review_comment` 和 `github.push`。这些旧版事件保持原有的行为。
`filters` 支持以下 GitHub 字段。对于每个由外部来源触发的 workflow,`from_users` 都必须非空。所有提供的过滤条件以 AND 组合。
| 字段 | 类型 | 适用于 | 含义 |
| ------------ | -------------------------- | ------------------------------------------------------------- | ---------------------------------------------------------- |
| `from_users` | 非空字符串列表 | 所有 GitHub 事件 | 允许启动该 workflow 的 GitHub 登录名。 |
| `repo` | 非空字符串 | 所有 GitHub 事件 | `owner/name` 形式的仓库。 |
| `connection` | 字符串 | 所有 GitHub 事件 | GitHub 连接的 slug。 |
| `contains` | 字符串 | issue、Pull Request 和评论事件 | issue 或 Pull Request 的标题加正文中,或评论正文中的子串。 |
| `pattern` | 字符串 | issue、Pull Request 和评论事件 | 同一段文本的开头。 |
| `label` | 非空字符串 | `github.issue_label_added`、`github.pull_request_label_added` | 本次投递添加的标签。 |
| `labels` | 由非空字符串组成的非空列表 | issue、Pull Request 和评论事件 | 每个所列标签都必须当前存在于该 issue 或 Pull Request 上。 |
`label` 和 `labels` 匹配 GitHub 标签时不区分大小写。`label` 检查发生变化的那一个标签;`labels` 检查当前完整的标签集合,并要求每一项都存在。例如,`labels: [bug, backend]` 要求同时存在 `bug` 和 `backend`。
`label` 只能与添加标签的事件一起使用,在其他事件上永远不会匹配。使用 `labels` 来要求条目所处的状态,包括由评论启动 workflow 的情况。
完整的分拣、Pull Request 审查和 ready-for-agent workflow,见 [GitHub 触发器](/docs/hub/triggers/github)。
### 输入和值 {#inputs-and-values}
输入的类型为 `type: string | number | boolean`,另有可选的 `required`、`default` 和 `choices`。`required` 和 `default` 不能同时使用。当某个输入可以选择权限相关的对象(例如环境或具名 Agent)时,必须提供有限的 `choices`。
值用于绑定表达式:
```yaml
values:
selected_environment: ${{ steps.classify.outputs.environment }}
selected_agent: ${{ steps.classify.outputs.agent }}
```
表达式可以读取已声明的 `paseo.inputs`、之前的 `steps.<id>.outputs` 以及 `values`。语法支持路径、JSON 字面量、括号、`!`、`==`、`!=`、`&&`、`||` 和 `??`。
用于选择环境或动态具名 Agent 的表达式,在激活时必须具有一个有限的、可能的字符串结果集合。每个结果都必须是一个已配置资源的名称。运行时的选择从不会退回到其他环境或 Agent。
### step {#steps}
| 字段 | 是否必填 | 说明 |
| ----------------- | -------- | ---------------------------------------------------------------------------------------- |
| `id` | 是 | 在 workflow 内唯一。 |
| `environment` | 是 | 字面的环境名称,或解析为某个环境名称的有限表达式。 |
| `max_runtime` | 是 | step 的硬性时间上限。 |
| `idle_timeout` | 是 | 空闲时间上限,不得超过 `max_runtime`。 |
| `startup_timeout` | 否 | step 启动的等待预算。默认值和限制见[启动超时](/docs/hub/configuration#startup-timeout)。 |
| `agent` | 是 | 具名 Agent、选择具名 Agent 的有限表达式,或一份完整的静态内联 Agent。 |
| `prompt` | 是 | 有序的 `text` 和 `include` 块。 |
| `if` | 否 | 决定该 step 是否运行的表达式。 |
| `env` | 否 | 来自连接值的环境变量。 |
| `output.schema` | 否 | 结构化 step 输出的 JSON Schema。 |
| `allow_outputs` | 否 | Provider 输出能力,可带 `max` 和 `required`。 |
| `auto_archive` | 否 | step 结束后归档该 Agent。 |
| `github` | 否 | 该 step 的显式 GitHub 权限。 |
内联 Agent 是静态且完整的:
```yaml
agent:
provider: codex
model: gpt-5.5
options:
approval_policy: never
sandbox_mode: read-only
```
表达式形式的 `agent` 用于选择具名 Agent。内联对象中的动态 Provider 字段会被拒绝。
### 提示词语义 {#prompt-semantics}
```yaml
prompt:
- include: partials/review.md
- text: |
<user-prompt>
${{ paseo.prompt }}
</user-prompt>
```
`${{ paseo.prompt }}` 是去掉 Provider 标记和已声明的开头 `key=value` 输入之后的规范化请求。它不会被改写,也不会附加事件上下文。
`${{ paseo.context }}` 让该 step 选择加入 Provider 上下文的具体化,并在提示词中把结果渲染为 JSON。它只能用在提示词文本中。除非 workflow 编写了这个表达式,否则 Hub 不会注入它。
include 相对于 `.paseo/workflows/` 解析,因此共享片段使用 `partials/<name>.md`。缺失的文件、绝对路径或越界路径、符号链接、内容不一致以及位于片段目录树之外的文件都会被拒绝。
### 输出能力 {#output-capabilities}
权限保留在使用它的 step 上:
```yaml
allow_outputs:
- type: discord.reply
max: 1
required: true
```
Slack workflow 使用 `slack.reply`;Discord workflow 使用 `discord.reply`。这项声明授予 `hub.reply`,提示词必须告诉 Agent 调用它。GitHub 没有回复输出;请使用显式的 [`github` 块](/docs/hub/github)。
每个 step 都会获得 `hub.finish_execution`。提示词必须告诉 Agent 何时调用它;Hub 不会追加完成或回复的指示。如果存在 `output.schema`,`hub.finish_execution` 需要一个与该 schema 匹配的 `output` 值。如果某个 `allow_outputs` 条目为 `required: true`,Agent 必须在完成之前发出该输出。`max` 默认为 `1`。
## 迁移单体文件 {#migrating-a-monolithic-file}
把 `environments` 保留在 `hub.yml` 中,把环境列表转换为具名映射,并把原先的每个触发器移到它自己的 `.paseo/workflows/<name>.yml` 文件中。把共享的提示词文件移到 `.paseo/workflows/partials/`。在 `agents` 下定义完整的具名 Agent 配置,并用有限的具名 Agent 选择替换动态的 Provider 字段。
Hub 不读取 TOML 或单体的 `triggers` 部分,CLI 也不会改写这两种格式。
完整的路由示例见 [workflow](/docs/hub/workflows)。
## Agent 延续 {#agent-continuation}
自包含的控制台触发器文档接受 `run.continuation`:
| 值 | 行为 |
| -------------------------------------------------------- | -------------------------------------------------------------------------- |
| `{mode: conversation}` | 默认值。为事件所属的对话复用项目中的 Agent;事件没有对话时创建新的 Agent。 |
| `{mode: key, key: "support-${{ paseo.inputs.ticket }}"}` | 为求值得到的自定义键复用项目中的 Agent。 |
| `{mode: new}` | 每次到达都创建新的 Agent。 |
键使用现有的表达式语法,必须解析为长度不超过 512 个字符的非空字符串。自定义键和 Provider 的对话标识位于不同的命名空间。不同项目中的相同键不会共享 Agent。
已有的会话会保留它的 daemon、Agent 配置、目标、环境和工具契约。为同一个键修改这些设置会失败并给出说明;请选择另一个键或 **New agent**。提示词和输出目标属于每次到达,可以变化。worktree 分支在会话首次创建时选定,并在之后的到达中复用。
后续消息会引导正在运行的 Agent,但不会延长它的运行截止时间或凭据有效期。当 `run.env` 中有 `run.github` 授权或连接令牌时,后续消息共享正在运行的 Agent 的凭据。所有请求都完成后,Hub 会撤销租用的令牌;下一次到达会用新的凭据启动新的 Agent。没有临时凭据的 Agent 在完成后可以被复用。
### 升级 {#upgrading}
在启用新版 Hub 之前,请先升级已连接的 Paseo daemon。Hub 需要 daemon 的常规 Agent RPC 和请求回执能力;较旧的主机会产生一个可操作的发起错误。
Hub 的数据库迁移会添加会话以及可为空的执行关联。已有的执行会保留它们已保存的启动契约和执行专属的 MCP 端点,直到完成。已有自包含触发器文档的新到达使用对话默认值。历史上的 Agent 不会被回填到会话中。
旧版的多 step workflow 文件包保持原有行为。把它转换为自包含触发器时,会显式写入 `mode: new`;准备好复用 Agent 时,在编辑器中修改它。
+29 -55
View File
@@ -1,14 +1,14 @@
---
title: Hub configuration
description: Generate, edit, and deploy organization triggers from your repository.
description: Author, validate, and deploy self-contained triggers from your repository with the Paseo CLI.
nav: Configuration
order: 70
order: 73
category: Hub
---
# Hub configuration
Each organization trigger is one self-contained YAML file. Keep triggers in your repository and deploy them with `paseo hub deploy`:
Each Hub trigger is one self-contained YAML file. Edit triggers in the Hub dashboard under **Triggers**, or keep them in your repository and deploy them with `paseo hub deploy`:
```text
.paseo/
@@ -16,11 +16,13 @@ Each organization trigger is one self-contained YAML file. Keep triggers in your
└── <trigger>.yml
```
See the [Trigger YAML reference](/docs/hub/configuration/reference) for every supported field.
## Generated starter trigger
Run `paseo hub init` from the repository the agent should work in. Setup selects an app connection and an available agent runtime, asks which user may trigger it, validates the result, and writes one file. It then asks whether to deploy. Interactive `paseo hub login` connects the daemon and points to this command; it does not write trigger files.
Run `paseo hub init` from the repository where the agent will work. Setup connects your daemon if needed, lets you choose a ready integration and an available agent runtime from that daemon, asks which user can trigger the bot, validates the result, and writes one starter file. It then asks whether to deploy.
For a Slack connection named `my-team`, the generated document looks like this:
For a Slack integration named `my-team`, setup generates:
```yaml
# .paseo/triggers/slack-help.yml
@@ -56,30 +58,34 @@ run:
required: true
```
`connection` is the app connection's slug in your organization. `target.daemon` is the connected daemon's slug and `target.cwd` is the absolute directory where you ran setup. `agent` contains the provider, model, and execution mode you selected from the daemon. The mode is required.
`connection` is the integration slug in your organization. `target.daemon` is your connected daemon's slug and `target.cwd` is the absolute repository path. `agent` carries the provider, model, and mode selected from that daemon.
`continuation.mode: conversation` keeps follow-ups in the same provider conversation on the same agent. The prompt asks the agent to reply and then call `hub.finish_execution`; replying alone does not finish the execution.
`continuation.mode: conversation` keeps follow-up mentions in the same thread on the same agent. The prompt instructs the agent to reply and call `finish_execution` because replying alone does not end the run.
A Discord starter uses `discord.mention`, your Discord user ID, and `discord.reply`. A GitHub starter uses `github.issue_comment`, restricts the repository to the current GitHub remote, and requires both `@paseo` and your GitHub username. GitHub's starter has no explicit reply output declaration.
A Discord starter uses `discord.mention`, your Discord user ID, and `discord.reply`. A GitHub starter uses `github.issue_comment`, scopes `repo` to the current GitHub remote, and requires both `@paseo` and your GitHub username.
Setup asks before replacing the selected trigger file. It preserves other triggers and any existing legacy bundle. Read [Hub security](/docs/hub/security) before widening `from_users` or the agent's authority.
Setup asks before replacing an existing starter file and leaves other trigger files untouched. Read [Hub security](/docs/hub/security) before widening `from_users` or agent authority.
## Startup timeout
Hub waits up to **two minutes** for agent startup, including worktree creation, provider startup, and initial prompt acceptance. For a slower machine, set `run.startup_timeout` in the trigger YAML:
Hub waits up to 2 minutes by default for an agent to start, including worktree creation, provider startup, and initial prompt acceptance. On a slower machine or large repository, set `run.startup_timeout`:
```yaml
name: inspect
on:
manual.run: {}
run:
target: { daemon: devbox, cwd: /workspace/project }
agent: { provider: codex, mode: full-access }
target:
daemon: devbox
cwd: /workspace/project
agent:
provider: codex
mode: full-access
startup_timeout: 5m
prompt: Inspect this repository and summarize its current state.
prompt: Inspect this repository and summarize its current state. Call finish_execution when done.
```
Use a positive duration in `ms`, `s`, `m`, or `h`, up to `24h`. Omitting the field uses `2m`. The existing `max_runtime` and `idle_timeout` limits still apply during startup and can expire sooner. This setting changes Hub's waiting budget; provider-specific timeouts remain in effect.
Use a positive duration in `ms`, `s`, `m`, or `h`, up to `24h`. `max_runtime` and `idle_timeout` still apply during startup and can expire sooner.
## Deploy from the CLI
@@ -91,57 +97,25 @@ paseo hub deploy --dry-run
paseo hub deploy
```
Both deploy commands discover direct `.paseo/triggers/*.yml` files in deterministic path order. The CLI rejects nested files, `.yaml` extensions, symlinked trigger paths, and unreadable files. It does not search parent directories.
Both commands read every direct `.paseo/triggers/*.yml` file in deterministic path order. The CLI rejects nested directories, `.yaml` extensions, symlinks, and unreadable files, and does not search parent directories.
Dry-run validates each document against Hub without storing a revision. Deployment validates all documents first, then installs them one at a time through the organization trigger API. Installation creates or updates a trigger by its YAML `name`. If a later install fails, the error lists the files already installed; those revisions remain active. Errors name paths without printing file contents or credentials.
`--dry-run` validates every file against Hub and your connected daemons without writing revisions. `paseo hub deploy` validates all files first, then installs each trigger by its YAML `name`.
If a later trigger fails to install, the error lists the files already installed. Redeploying an existing webhook trigger name preserves its webhook URL and secret.
Origin precedence:
1. `--hub`
1. Explicit command origin or `--hub`
2. `PASEO_HUB_URL`
3. Active stored login
3. Active stored CLI login
4. `https://hub.paseo.sh`
Credential precedence:
1. `--api-key`
2. `PASEO_HUB_API_KEY`
3. Stored login for the exact resolved origin
3. Stored CLI login for the exact resolved origin
Flags and environment keys are not stored. Endpoint and credential behavior is unchanged between deploy and dry-run.
Flags and environment API keys are never written to disk.
## Legacy project bundles
Existing project bundles use `.paseo/hub.yml`, direct `.paseo/workflows/*.yml` files, and referenced files below `.paseo/workflows/partials/`. `hub.yml` owns named environments and agents; each workflow owns its trigger and ordered steps.
Select the legacy deployment path explicitly:
```sh
paseo hub deploy --project my-project --dry-run
paseo hub deploy --project my-project
```
These commands send the complete bundle through the project configuration API. Dry-run validates without recording or activating a revision. `paseo hub init` does not create or migrate these bundles.
The following source and revision behavior applies to legacy project bundles.
## GitHub sync
A push to the configuration repository's default branch starts a sync:
1. Hub discovers the canonical bundle at that exact commit.
2. It parses every source file and resolves prompt partials.
3. It validates named resources, expressions, connections, and daemon availability.
4. On success, the new immutable revision becomes active.
**Sync now** performs the same operation on demand. Failures retain their source path and authored field. A failed sync never replaces the active revision.
## Revisions and source changes
Revisions retain the exact authored files needed to inspect or redeploy them. Rolling back activates an earlier revision. The next valid GitHub push activates a new revision again.
GitHub-backed configuration is read-only in the dashboard. Switching to manual preserves source documents; it does not collapse the bundle into one generated file.
The configuration repository may differ from repositories named by `filters.repo`. Protect it because changing the bundle can select connections, daemons, working directories, agents, and outputs. See [Hub security](/docs/hub/security).
Next: the [configuration reference](/docs/hub/configuration/hub-yml) and [workflow examples](/docs/hub/workflows).
Next: [Trigger YAML reference](/docs/hub/configuration/reference).
+32 -58
View File
@@ -1,12 +1,12 @@
---
title: Hub 配置
description: 从你的仓库生成、编辑和部署组织触发器。
description: 使用 Paseo CLI 从仓库编写、校验和部署自包含触发器。
nav: 配置
---
# Hub 配置 {#hub-configuration}
每个组织触发器都是一个自包含的 YAML 文件。把触发器保存在你的仓库中,并用 `paseo hub deploy` 部署:
每个 Hub 触发器都是一个自包含的 YAML 文件。你可以在 Hub 控制台的 **Triggers** 中编辑触发器,也可以将它们保存在仓库中并用 `paseo hub deploy` 部署:
```text
.paseo/
@@ -14,11 +14,13 @@ nav: 配置
└── <trigger>.yml
```
## 生成的起步触发器 {#generated-starter-trigger}
所有支持的字段见[触发器 YAML 参考](/docs/hub/configuration/reference)。
在 Agent 要工作的仓库中运行 `paseo hub init`。设置流程会选择一个应用连接和一个可用的 Agent 运行时,询问哪个用户可以触发它,校验结果并写入一个文件,然后询问是否部署。交互式的 `paseo hub login` 会连接 daemon 并提示你运行这条命令;它不会写入触发器文件。
## 生成的入门触发器 {#generated-starter-trigger}
对于名为 `my-team` 的 Slack 连接,生成的文档如下:
在 Agent 要工作的仓库中运行 `paseo hub init`。设置流程会按需连接 daemon,让你选择就绪的集成和该 daemon 上可用的 Agent 运行时,询问允许触发机器人的用户,校验结果并写入一个入门文件,然后询问是否立即部署。
对于名为 `my-team` 的 Slack 集成,生成的文档如下:
```yaml
# .paseo/triggers/slack-help.yml
@@ -54,32 +56,36 @@ run:
required: true
```
`connection` 是应用连接在你组织中的 slug。`target.daemon` 是已连接 daemon 的 slug,`target.cwd` 是你运行设置流程时所在的绝对目录。`agent` 包含你从 daemon 中选择的 Provider、模型和执行模式。模式是必填的。
`connection` 是你组织中的集成 slug。`target.daemon` 是已连接 daemon 的 slug,`target.cwd` 是仓库的绝对路径。`agent` 记录从该 daemon 选择的 Provider、模型和模式。
`continuation.mode: conversation` 让后续请求在同一个 Agent 的同一段 Provider 对话中进行。提示词要求 Agent 先回复,再调用 `hub.finish_execution`;只回复并不会结束执行。
`continuation.mode: conversation` 会将同一讨论串中的后续提及保留在同一个 Agent 上。提示词要求 Agent 回复并调用 `finish_execution`,因为仅回复不会结束运行。
Discord 起步配置使用 `discord.mention`、你的 Discord 用户 ID 和 `discord.reply`。GitHub 起步配置使用 `github.issue_comment`,把仓库限制为当前的 GitHub 远程仓库,并同时要求 `@paseo` 和你的 GitHub 用户名。GitHub 起步配置没有显式的回复输出声明。
Discord 入门触发器使用 `discord.mention`、你的 Discord 用户 ID 和 `discord.reply`。GitHub 入门触发器使用 `github.issue_comment`,将 `repo` 限定为当前 GitHub 远程仓库,并同时要求 `@paseo` 和你的 GitHub 用户名。
设置流程在替换所选的触发器文件之前会先询问。它会保留其他触发器以及任何已有的旧配置包。在扩大 `from_users` 或 Agent 的权限之前,请阅读 [Hub 安全](/docs/hub/security)。
如果入门文件已存在,设置流程会在替换前询问,并保留其他触发器文件。扩大 `from_users` 或 Agent 权限前,请先阅读 [Hub 安全](/docs/hub/security)。
## 启动超时 {#startup-timeout}
Hub 最多等待 **两分钟**让 Agent 启动,包括创建 worktree、启动 Provider 以及接受初始提示词。对于较慢的机器,请在触发器 YAML 中设置 `run.startup_timeout`:
Hub 默认最多等待 2 分钟供 Agent 启动,包括创建 worktree、启动 Provider 和接受初始提示词。对于较慢的机器或大型仓库,可以设置 `run.startup_timeout`:
```yaml
name: inspect
on:
manual.run: {}
run:
target: { daemon: devbox, cwd: /workspace/project }
agent: { provider: codex, mode: full-access }
target:
daemon: devbox
cwd: /workspace/project
agent:
provider: codex
mode: full-access
startup_timeout: 5m
prompt: Inspect this repository and summarize its current state.
prompt: Inspect this repository and summarize its current state. Call finish_execution when done.
```
使用以 `ms`、`s`、`m` 或 `h` 为单位的正数时长,最长 `24h`。省略该字段时使用 `2m`。已有的 `max_runtime` 和 `idle_timeout` 限制在启动期间仍然适用,并且可能更早到期。这个设置改变的是 Hub 的等待预算;Provider 自己的超时设置仍然有效。
使用带单位的正时长(`ms`、`s`、`m` 或 `h`),最长 `24h`。`max_runtime` 和 `idle_timeout` 在启动阶段同样生效,可能更早到期。
## 通过 CLI 部署 {#deploy-from-the-cli}
## 从 CLI 部署 {#deploy-from-the-cli}
在仓库根目录运行:
@@ -89,57 +95,25 @@ paseo hub deploy --dry-run
paseo hub deploy
```
两条部署命令都会按确定的路径顺序发现直接位于 `.paseo/triggers/*.yml` 的文件。CLI 会拒绝嵌套的文件、`.yaml` 扩展名、符号链接的触发器路径以及无法读取的文件。它不会搜索上级目录。
两个命令都会按确定的路径顺序读取直接位于 `.paseo/triggers/*.yml` 下的文件。CLI 会拒绝嵌套目录、`.yaml` 扩展名、符号链接和不可读文件,并且不会向上搜索父目录。
dry-run 会让 Hub 校验每个文档,但不保存版本。部署会先校验所有文档,然后通过组织触发器 API 逐个安装。安装会按 YAML 中的 `name` 创建或更新触发器。如果之后的某次安装失败,错误信息会列出已经安装的文件;这些版本仍然生效。错误信息只给出路径,不会打印文件内容或凭据。
`--dry-run` 会对照 Hub 和已连接的 daemon 校验所有文件,但不写入版本。`paseo hub deploy` 会先校验全部文件,再按 YAML 中的 `name` 逐个安装。
地址的优先级:
如果后面的触发器安装失败,错误信息会列出已成功安装的文件。重新部署同名的 webhook 触发器会保留它的 webhook URL 和密钥。
1. `--hub`
地址优先级:
1. 显式命令地址或 `--hub`
2. `PASEO_HUB_URL`
3. 当前保存的登录
3. 当前已保存的 CLI 登录
4. `https://hub.paseo.sh`
凭据的优先级:
凭据优先级:
1. `--api-key`
2. `PASEO_HUB_API_KEY`
3. 与最终解析出的地址完全一致的已保存登录
3. 与精确解析地址匹配的已保存 CLI 登录
参数和环境变量中的密钥不会被保存。端点和凭据的行为在 deploy 和 dry-run 之间完全一致。
命令行标志和环境变量传入的 API 密钥永远不会写入磁盘。
## 旧版项目配置包 {#legacy-project-bundles}
现有的项目配置包使用 `.paseo/hub.yml`、直接位于 `.paseo/workflows/*.yml` 的文件,以及 `.paseo/workflows/partials/` 下被引用的文件。`hub.yml` 负责命名环境和 Agent;每个 workflow 负责自己的触发器和有序的 step。
显式选择旧版部署方式:
```sh
paseo hub deploy --project my-project --dry-run
paseo hub deploy --project my-project
```
这些命令会通过项目配置 API 发送完整的配置包。dry-run 只做校验,不会记录或激活版本。`paseo hub init` 不会创建或迁移这些配置包。
以下关于来源和版本的行为适用于旧版项目配置包。
## GitHub 同步 {#github-sync}
向配置仓库的默认分支推送会启动一次同步:
1. Hub 在该提交中发现标准的配置包。
2. 它解析每个源文件并解析提示词片段。
3. 它校验命名资源、表达式、连接以及 daemon 的可用性。
4. 成功后,新的不可变版本成为生效版本。
**Sync now** 会按需执行同样的操作。失败信息会保留源路径和编写的字段。同步失败永远不会替换生效版本。
## 版本与来源变更 {#revisions-and-source-changes}
版本会保留查看或重新部署所需的完整原始文件。回滚会激活一个更早的版本。下一次有效的 GitHub 推送会再次激活一个新版本。
基于 GitHub 的配置在控制台中是只读的。切换到手动会保留源文档;它不会把配置包合并成一个生成的文件。
配置仓库可以不同于 `filters.repo` 中指定的仓库。请保护好它,因为修改配置包可以选择连接、daemon、工作目录、Agent 和输出。参见 [Hub 安全](/docs/hub/security)。
下一步:[配置参考](/docs/hub/configuration/hub-yml)和 [workflow 示例](/docs/hub/workflows)。
下一步:[触发器 YAML 参考](/docs/hub/configuration/reference)。
+156
View File
@@ -0,0 +1,156 @@
---
title: Trigger YAML reference
description: Complete field reference for Hub self-contained trigger documents in .paseo/triggers/*.yml.
nav: Trigger YAML reference
order: 74
category: Hub
---
# Trigger YAML reference
Each `.paseo/triggers/<name>.yml` file defines one self-contained Hub trigger. The Hub dashboard YAML view and `POST /api/v1/triggers/install` accept the same format.
## Top-level fields
| Field | Required | Default | Notes |
| ------------- | -------- | ----------------- | ------------------------------------------------------------------------------------------------- |
| `name` | yes | none | Unique trigger identifier (`^[a-z][a-z0-9_-]*$`). Redeploying updates by `name`. |
| `enabled` | no | `true` | Disabled triggers keep their configuration and stop accepting new runs. |
| `on` | yes | none | Non-empty map of event names to event definitions (`connection`, `filters`, `recurrence`). |
| `inputs` | no | none | Typed invocation headers (`type: string \| number \| boolean`, `required`, `default`, `choices`). |
| `max_runtime` | no | `run.max_runtime` | Hard limit for the whole trigger run, up to `24h`. |
| `run` | yes | none | Target daemon, agent configuration, continuation, prompt, limits, tools, and outputs. |
## Event definitions (`on`)
Each key under `on` is an event name:
- Provider events (`github.*`, `linear.*`, `slack.mention`, `discord.mention`) accept optional `connection` (integration slug) and `filters`. See [Triggers](/docs/hub/triggers#events) for the full event and filter tables.
- `schedule.tick` requires `recurrence` (`start`, `rule`, `timezone`) and rejects `connection` and `filters`. See [Scheduled triggers](/docs/hub/triggers/schedules).
- `webhook.received` accepts an empty object `{}` and rejects `connection` and `filters`. See [Inbound webhooks](/docs/hub/triggers/webhooks).
- `manual.run` accepts `{}` or `filters.from_users` for API dispatch. See [Hub public API](/docs/hub/api#manual-run-dispatch).
One trigger document can list more than one event under `on`. The dashboard visual form edits single-event triggers, and multi-event triggers stay editable in YAML view.
## Target and worktree
`run.target` selects the daemon and directory where the agent executes:
| Field | Required | Notes |
| ---------- | -------- | ------------------------------------------------------------------------------ |
| `daemon` | yes | Connected daemon slug with `hub.execute` permission. |
| `cwd` | yes | Existing directory on that daemon, with an absolute path that starts with `/`. |
| `worktree` | no | Optional git worktree mode: `branch-off`, `checkout-branch`, or `checkout-pr`. |
For example, `/home/me/project` uses the required path format. Hub rejects Windows drive paths such as `C:\work\project`.
Worktree modes:
- `branch-off`: requires `newBranch` and optional `base`. Embed `${{ paseo.execution.id }}` in `newBranch` (for example `trigger-${{ paseo.execution.id }}`) so each execution gets a unique branch that survives retries. `${{ paseo.execution.id }}` is the only expression accepted in `newBranch`.
- `checkout-branch`: requires literal `branch`.
- `checkout-pr`: requires positive integer `prNumber`.
## Agent selection
`run.agent` defines either one static agent configuration or a finite choice selected from an input:
| Field | Required | Notes |
| ------------------ | -------- | ---------------------------------------------------------------------------------------------------------------------------- |
| `provider` | yes | Any provider configured on the target daemon (for example `codex`, `claude`, `opencode`, `pi`, or a custom/plugin provider). |
| `model` | no | Provider model ID. |
| `mode` | no | Provider execution mode ID. Required in the dashboard form when the provider offers modes. |
| `thinkingOptionId` | no | Provider thinking option ID. |
| `options` | no | JSON-safe provider-native options object, passed through without renaming. |
Hub asks the connected daemon to validate `provider`, `model`, `mode`, `thinkingOptionId`, and `options` whenever you save or deploy.
To let an invocation input choose between complete predefined agent configurations, use `select` and `choices`:
```yaml
name: choose-agent
on:
manual.run: {}
inputs:
agent:
type: string
required: true
choices: [codex-read, claude-work]
run:
target:
daemon: devbox
cwd: /workspace/project
agent:
select: ${{ paseo.inputs.agent }}
choices:
codex-read:
provider: codex
mode: read-only
claude-work:
provider: claude
mode: bypassPermissions
prompt: Handle this request and call finish_execution.
```
Dynamic fields inside an inline agent object are rejected. Every possible `select` result must match a key in `choices`.
## Agent continuation
`run.continuation` controls whether new arrivals reuse an existing agent or start a new one:
| Value | Behavior |
| --------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| `{ mode: conversation }` | Default. Reuses the agent for the same Slack or Discord thread, GitHub issue or PR, or Linear issue. Starts a new agent when no conversation exists. |
| `{ mode: key, key: "ticket-${{ paseo.inputs.ticket }}" }` | Reuses the agent for the evaluated key (non-empty string up to 512 characters). |
| `{ mode: new }` | Starts a new agent for every arrival. |
A continuing agent keeps its original daemon, working directory, worktree branch, agent configuration, `background` flag, and tool grants. Changing any of those settings for the same continuation key fails until you switch to `{ mode: new }` or pick a new key.
When a follow-up arrives while the agent is busy, Hub steers the running agent without extending its original runtime deadline. Pass the prompt's `executionId` to `reply` and `finish_execution` so outputs bind to the right arrival.
## Prompt, context, and title
| Field | Required | Default | Notes |
| ----------------- | -------- | ------- | -------------------------------------------------------------------------------------------------- |
| `prompt` | yes | none | Instruction text sent to the agent. |
| `title` | no | none | Optional Paseo workspace title template (literal text plus `${{ paseo.execution.id }}`). |
| `max_runtime` | no | `2h` | Hard runtime limit, up to `24h`. |
| `idle_timeout` | no | `10m` | Idle timeout, no longer than `max_runtime`. |
| `startup_timeout` | no | `2m` | Waiting budget for worktree creation and provider startup, up to `24h`. |
| `auto_archive` | no | `true` | Archives the workspace after execution finishes. |
| `background` | no | `false` | Creates a background Paseo workspace hidden from default workspace lists. Older daemons ignore it. |
Prompt expressions:
- `${{ paseo.prompt }}` inserts the complete received message text for provider events, or the framed webhook body for `webhook.received`. For `webhook.received`, omitting `${{ paseo.prompt }}` appends the framed body automatically.
- `${{ paseo.context }}` opts the run into provider context materialization (thread history, issue metadata, schedule metadata, or attachment descriptors) rendered as JSON. Hub does not inject ambient context unless you author `${{ paseo.context }}`.
- `${{ paseo.inputs.<name> }}` inserts a declared input value.
Wrap untrusted external text in a clear delimiter such as `<user-prompt>...</user-prompt>`.
## Output capabilities
Hub attaches its execution MCP server to every run and always exposes `finish_execution`.
Hub grants the `reply` tool when the event has an issue, pull request, or thread to reply to. Replies are optional and unlimited by default.
A `github.push` event has no reply destination. If you set `run.outputs.github.reply.required: true` for a push, Hub fails the run before it starts the agent.
Set `run.outputs` to cap replies with `max` or require a reply before `finish_execution`.
```yaml
run:
outputs:
slack.reply:
max: 1
required: true
```
Supported reply capability keys are `github.reply`, `linear.reply`, `slack.reply`, and `discord.reply`. Hub does not rewrite your prompt, so tell the agent when to call `reply` and `finish_execution`.
To require structured JSON output on `finish_execution`, set `run.output.schema` to a JSON Schema object.
## Tools, GitHub, and environment
- `run.tools` grants scoped Slack and Discord MCP tools (`read` and `post` on explicit channel IDs). See [Integration tools](/docs/hub/tools).
- `run.github` mints a scoped `GH_TOKEN` and isolated git configuration. See [GitHub access](/docs/hub/github).
- `run.env` injects environment variables, including `${{ paseo.connections.<slug>.token }}`.
@@ -0,0 +1,154 @@
---
title: 触发器 YAML 参考
description: .paseo/triggers/*.yml 中自包含 Hub 触发器文档的完整字段参考。
nav: 触发器 YAML 参考
---
# 触发器 YAML 参考 {#trigger-yaml-reference}
每个 `.paseo/triggers/<name>.yml` 文件定义一个自包含的 Hub 触发器。Hub 控制台的 YAML 视图和 `POST /api/v1/triggers/install` 接受相同的格式。
## 顶层字段 {#top-level-fields}
| 字段 | 必填 | 默认值 | 说明 |
| ------------- | ---- | ----------------- | ------------------------------------------------------------------------------------------- |
| `name` | 是 | 无 | 唯一触发器标识符(`^[a-z][a-z0-9_-]*$`)。重新部署会按 `name` 更新。 |
| `enabled` | 否 | `true` | 禁用的触发器保留配置,并停止接受新运行。 |
| `on` | 是 | 无 | 非空映射,键为事件名,值为事件定义(`connection`、`filters`、`recurrence`)。 |
| `inputs` | 否 | 无 | 带类型的调用头部(`type: string \| number \| boolean`、`required`、`default`、`choices`)。 |
| `max_runtime` | 否 | `run.max_runtime` | 整次触发运行的硬性上限,最长 `24h`。 |
| `run` | 是 | 无 | 目标 daemon、Agent 配置、会话延续、提示词、运行限制、工具和输出。 |
## 事件定义(`on`) {#event-definitions-on}
`on` 下的每个键都是一个事件名:
- Provider 事件(`github.*`、`linear.*`、`slack.mention`、`discord.mention`)接受可选的 `connection`(集成 slug)和 `filters`。完整事件和过滤条件表见[触发器](/docs/hub/triggers#events)。
- `schedule.tick` 要求设置 `recurrence`(`start`、`rule`、`timezone`),并拒绝 `connection` 和 `filters`。参见[定时触发器](/docs/hub/triggers/schedules)。
- `webhook.received` 接受空对象 `{}`,并拒绝 `connection` 和 `filters`。参见[入站 webhook](/docs/hub/triggers/webhooks)。
- `manual.run` 接受 `{}` 或用于 API 派发的 `filters.from_users`。参见 [Hub 公开 API](/docs/hub/api#manual-run-dispatch)。
一个触发器文档可以在 `on` 下声明多个事件。控制台的可视化表单编辑单事件触发器,多事件触发器可在 YAML 视图中编辑。
## 目标与 worktree {#target-and-worktree}
`run.target` 选择执行 Agent 的 daemon 和目录:
| 字段 | 必填 | 说明 |
| ---------- | ---- | ---------------------------------------------------------------------------- |
| `daemon` | 是 | 拥有 `hub.execute` 权限的已连接 daemon slug。 |
| `cwd` | 是 | 该 daemon 上已有的目录,使用以 `/` 开头的绝对路径。 |
| `worktree` | 否 | 可选的 git worktree 模式:`branch-off`、`checkout-branch` 或 `checkout-pr`。 |
例如,`/home/me/project` 符合路径格式。Hub 会拒绝 `C:\work\project` 这类 Windows 盘符路径。
worktree 模式:
- `branch-off`:需要 `newBranch` 和可选的 `base`。在 `newBranch` 中嵌入 `${{ paseo.execution.id }}`(例如 `trigger-${{ paseo.execution.id }}`),让每次执行获得唯一分支并在重试时保持一致。`newBranch` 只接受 `${{ paseo.execution.id }}` 表达式。
- `checkout-branch`:需要字面量 `branch`。
- `checkout-pr`:需要正整数 `prNumber`。
## Agent 选择 {#agent-selection}
`run.agent` 可以定义一个静态 Agent 配置,或通过输入在有限选项中进行选择:
| 字段 | 必填 | 说明 |
| ------------------ | ---- | ------------------------------------------------------------------------------------------------------ |
| `provider` | 是 | 目标 daemon 上配置的任意 Provider(例如 `codex`、`claude`、`opencode`、`pi` 或自定义/插件 Provider)。 |
| `model` | 否 | Provider 模型 ID。 |
| `mode` | 否 | Provider 执行模式 ID。当 Provider 提供模式时,控制台表单要求填写。 |
| `thinkingOptionId` | 否 | Provider 思考选项 ID。 |
| `options` | 否 | JSON 安全的 Provider 原生选项对象,原样透传不重命名。 |
保存或部署时,Hub 会请已连接的 daemon 校验 `provider`、`model`、`mode`、`thinkingOptionId` 和 `options`。
如需让调用输入在若干完整的预定义 Agent 配置之间选择,请使用 `select` 和 `choices`:
```yaml
name: choose-agent
on:
manual.run: {}
inputs:
agent:
type: string
required: true
choices: [codex-read, claude-work]
run:
target:
daemon: devbox
cwd: /workspace/project
agent:
select: ${{ paseo.inputs.agent }}
choices:
codex-read:
provider: codex
mode: read-only
claude-work:
provider: claude
mode: bypassPermissions
prompt: Handle this request and call finish_execution.
```
内联 Agent 对象中的动态字段会被拒绝。`select` 的每一个可能结果都必须对应 `choices` 中的键。
## Agent 延续 {#agent-continuation}
`run.continuation` 控制新到达的事件是复用现有 Agent 还是启动新 Agent:
| 值 | 行为 |
| --------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
| `{ mode: conversation }` | 默认值。在同一 Slack 或 Discord 讨论串、GitHub issue 或 PR、Linear issue 上复用 Agent;无对话时启动新 Agent。 |
| `{ mode: key, key: "ticket-${{ paseo.inputs.ticket }}" }` | 按求值后的键复用 Agent(最长 512 个字符的非空字符串)。 |
| `{ mode: new }` | 每次到达都启动全新的 Agent。 |
持续运行的 Agent 会保留原有的 daemon、工作目录、worktree 分支、Agent 配置、`background` 标志和工具授权。如果对同一个延续键修改其中任一项,运行会失败,需先切换到 `{ mode: new }` 或更换延续键。
当 Agent 正忙时到达的后续事件会引导正在运行的 Agent,但不会延长原运行超时。调用 `reply` 和 `finish_execution` 时请传入提示词中的 `executionId`,确保输出绑定到正确的请求。
## 提示词、上下文与标题 {#prompt-context-and-title}
| 字段 | 必填 | 默认值 | 说明 |
| ----------------- | ---- | ------- | ----------------------------------------------------------------------- |
| `prompt` | 是 | 无 | 发送给 Agent 的指令文本。 |
| `title` | 否 | 无 | 可选的 Paseo 工作区标题模板(字面文本加 `${{ paseo.execution.id }}`)。 |
| `max_runtime` | 否 | `2h` | 运行硬性上限,最长 `24h`。 |
| `idle_timeout` | 否 | `10m` | 空闲超时,不能超过 `max_runtime`。 |
| `startup_timeout` | 否 | `2m` | 创建 worktree 和启动 Provider 的等待预算,最长 `24h`。 |
| `auto_archive` | 否 | `true` | 执行结束后归档工作区。 |
| `background` | 否 | `false` | 创建在默认工作区列表中隐藏的后台工作区。旧版 daemon 会忽略它。 |
提示词表达式:
- `${{ paseo.prompt }}` 插入 Provider 事件收到的完整消息文本,或 `webhook.received` 包装后的 webhook 请求体。对于 `webhook.received`,省略 `${{ paseo.prompt }}` 时会自动追加包装后的请求体。
- `${{ paseo.context }}` 为本次运行显式开启 Provider 上下文物化(讨论串历史、issue 元数据、定时元数据或附件描述符),以 JSON 渲染。除非显式编写 `${{ paseo.context }}`,Hub 不会自动注入环境上下文。
- `${{ paseo.inputs.<name> }}` 插入已声明的输入值。
请用清晰边界(例如 `<user-prompt>...</user-prompt>`)包裹不可信外部文本。
## 输出能力 {#output-capabilities}
Hub 会为每次运行挂载执行 MCP 服务器,并始终提供 `finish_execution`。
当事件有关联的 issue、Pull Request 或讨论串可供回复时,Hub 会授予 `reply` 工具。默认情况下,回复可选且不限次数。
`github.push` 事件没有回复目标。如果为推送事件设置 `run.outputs.github.reply.required: true`,Hub 会在启动 Agent 前将运行标记为失败。
通过 `run.outputs` 设置 `max` 可限制回复次数,也可以要求 Agent 在调用 `finish_execution` 前至少回复一次。
```yaml
run:
outputs:
slack.reply:
max: 1
required: true
```
支持的回复能力键为 `github.reply`、`linear.reply`、`slack.reply` 和 `discord.reply`。Hub 不会改写提示词,因此需要在提示词中告诉 Agent 何时调用 `reply` 和 `finish_execution`。
如需在 `finish_execution` 上要求结构化 JSON 输出,请将 `run.output.schema` 设为 JSON Schema 对象。
## 工具、GitHub 与环境变量 {#tools-github-and-environment}
- `run.tools` 授予受控的 Slack 和 Discord MCP 工具(针对显式频道 ID 的 `read` 和 `post`)。参见[集成工具](/docs/hub/tools)。
- `run.github` 签发受控的 `GH_TOKEN` 和隔离的 git 配置。参见 [GitHub 访问](/docs/hub/github)。
- `run.env` 注入环境变量,包括 `${{ paseo.connections.<slug>.token }}`。
+66 -51
View File
@@ -1,6 +1,6 @@
---
title: Daemons in Hub
description: Enroll a machine with Hub, reference it from configuration, and understand what Hub owns once it is connected.
description: Enroll a Paseo daemon with Hub, grant execution permission, and target it from triggers.
nav: Daemons
order: 63
category: Hub
@@ -8,9 +8,9 @@ category: Hub
# Daemons in Hub
A daemon is one of your machines running the Paseo daemon. Enroll it once with your Hub organization, then triggers can reference it.
A daemon is one of your machines running the Paseo daemon. Enroll it once with your Hub organization, grant execution permission, and reference its slug in your triggers.
## Connect
## Connect a daemon
Log in from the machine first:
@@ -18,33 +18,31 @@ Log in from the machine first:
paseo hub login https://hub.example.com
```
The CLI prints a URL and a verification code and opens your browser. The approved login is stored under `PASEO_HOME`.
The CLI prints a URL and verification code and opens your browser. After approval, Paseo stores an organization-scoped CLI login under `PASEO_HOME`.
In an interactive terminal, login offers to connect this daemon and separately asks whether to allow Hub automations to run agents. Connection defaults to yes; execution permission defaults to no. It then links to **Triggers** and prints `paseo hub init` for creating a starter trigger as code. `--json` or non-TTY login only logs in. [Quickstart](/docs/hub/quickstart) walks through connection and initialization.
In an interactive terminal, `login` offers to connect this daemon and separately asks whether to allow Hub automations to run agents. Connection defaults to yes, and execution permission defaults to no. `--json` and non-TTY logins do not prompt.
Enroll the daemon on its own when you declined, or when the machine is already logged in:
If you skipped connection during login, enroll the daemon separately:
```sh
paseo hub connect
```
`connect` uses the active login to request a single-use enrollment token. The daemon exchanges it for its own relationship credential; your CLI login is never stored as daemon authority.
`connect` uses your active login to request a single-use enrollment token. The daemon exchanges that token for its own relationship credential, so your CLI login is never stored as daemon authority.
Hub derives the daemon's initial slug from its hostname. If that slug is already used in the organization, Hub adds a short daemon ID suffix. You can rename the daemon later in Hub.
Hub derives the daemon's initial slug from its hostname using lowercase words joined by hyphens, such as `build-studio`. If that slug is already taken in the organization, Hub appends a short daemon ID suffix.
Each daemon has two identifiers: an immutable generated ID and a friendly slug. Hub normalizes slugs with lowercase words joined by hyphens, so `Build Studio` becomes `build-studio`. The slug is what the dashboard shows and what configuration references.
You can rename the slug later in Hub without changing the immutable daemon ID, then update any triggers that reference the old slug.
You can rename the slug later without changing the daemon ID. Renaming after a configuration is active means updating that configuration.
For unattended setup, pass an organization API key without storing it:
For unattended setup, pass an organization API key through the environment:
```sh
PASEO_HUB_URL=https://hub.example.com PASEO_HUB_API_KEY=paseo_pk_... paseo hub connect
```
Origin precedence is explicit `[origin]`, `PASEO_HUB_URL`, active stored login, then `https://hub.paseo.sh`. An explicit `--api-key <secret>` takes precedence over the environment and an exact-origin stored login.
Origin precedence is explicit `[origin]` or `--hub`, then `PASEO_HUB_URL`, then the active stored login, then `https://hub.paseo.sh`. An explicit `--api-key <secret>` takes precedence over environment variables and stored logins.
Check and undo:
Check status or disconnect a daemon:
```sh
paseo hub status
@@ -52,22 +50,18 @@ paseo hub disconnect
paseo hub disconnect --force # drop local authority when Hub is unreachable
```
One daemon has one Hub relationship. Connecting a daemon that already has one is refused.
One daemon connects to one Hub organization at a time. Connecting a daemon that already belongs to a Hub is refused.
`paseo hub logout` removes the active CLI login. The daemon's relationship is a separate identity and stays connected.
In an interactive terminal, logout offers to disconnect a daemon enrolled with the same Hub. Accepting disconnects first and then deletes the login, so a failed disconnection keeps your credential. Declining removes only the login.
Noninteractive and `--json` logout never disconnect implicitly:
`paseo hub logout` removes the stored CLI login. In an interactive terminal, it offers to disconnect a daemon connected to the same Hub first. In `--json` or non-interactive mode, `logout` never disconnects the daemon unless you pass `--disconnect-daemon`:
```sh
paseo hub logout --disconnect-daemon # remove both identities
paseo hub logout --disconnect-daemon --force # drop local authority when Hub is unreachable
paseo hub logout --disconnect-daemon
paseo hub logout --disconnect-daemon --force
```
## Let Hub run agents on it
## Grant execution permission
Enrolling a daemon does not let Hub start agents on it. That is the separate `hub.execute` permission, which login asks about and defaults to no. Grant it from the machine at any time:
Enrolling a daemon does not allow Hub to start agents on it. Grant the `hub.execute` permission from that machine:
```sh
paseo hub permissions list
@@ -75,50 +69,71 @@ paseo hub permissions grant hub.execute
paseo hub permissions revoke hub.execute
```
Until it is granted, Hub keeps the daemon for identity and presence only. The Daemons page shows it as **Connected only** with the grant command, and Home's checklist reads **Cannot run agents**. [Hub security](/docs/hub/security#choose-daemon-authority) covers what the permission allows once granted.
Until `hub.execute` is granted, Hub tracks the daemon for identity and presence only. **Daemons** marks it as **Connected only** and **Home** notes that it cannot run agents. See [Choose daemon authority](/docs/hub/security#choose-daemon-authority) for what `hub.execute` permits.
## Reference it from configuration
## Target a daemon from a trigger
Reference the daemon slug and an existing working directory under `run.target`:
```yaml
environments:
dev:
kind: daemon
name: repo-triage
on:
manual.run: {}
run:
target:
daemon: my-macbook
cwd: /Users/you/code/your-repo
agent:
provider: codex
mode: full-access
prompt: Inspect the repository status and call hub.finish_execution.
```
`daemon` is the friendly slug. It resolves to the immutable daemon ID when the configuration activates, so a daemon that no longer exists fails activation instead of failing at dispatch.
`daemon` resolves to the immutable daemon ID when you save or deploy the trigger. `cwd` is an absolute path that already exists on that machine. Hub does not clone repositories for you.
`cwd` is a path on that machine. Hub does not clone anything for you; the directory must already exist.
To keep executions off your working tree, add a worktree:
To isolate each run on its own git branch instead of editing your working tree, add a `worktree` block:
```yaml
worktree:
mode: branch-off
newBranch: trigger-${{ paseo.execution.id }}
base: origin/main
name: isolate-fix
on:
manual.run: {}
run:
target:
daemon: build-server
cwd: /workspace/project
worktree:
mode: branch-off
newBranch: trigger-${{ paseo.execution.id }}
base: origin/main
agent:
provider: codex
mode: full-access
prompt: Run tests and call hub.finish_execution.
```
`${{ paseo.execution.id }}` renders the execution's UUID, so every execution gets its own branch off `origin/main`.
`${{ paseo.execution.id }}` renders the execution UUID, giving each run a unique branch off `origin/main` that survives retries and recovery. See [Trigger YAML reference](/docs/hub/configuration/reference#target-and-worktree) and [Git worktrees](/docs/worktrees).
[Environment fields](/docs/hub/configuration/hub-yml#environments) lists what `newBranch` accepts. See [Git worktrees](/docs/worktrees) for setup hooks and scripts.
## Provider discovery
## What Hub owns
When you select a daemon and working directory in the Hub trigger editor, Hub asks that daemon for its configured providers, models, execution modes, and thinking options.
For agents it dispatched, Hub owns creation, reconnect recovery, output observation, and completion. Agents you start yourself are untouched.
Hub works with any provider configured on your Paseo daemon, including Claude Code, Codex, OpenCode, Pi, and custom or plugin providers.
If Hub loses the create response, or the daemon restarts mid-execution, Hub resends the same create intent with the same execution id. The daemon returns the existing agent rather than running the prompt again. An agent that closed or errored is recorded as interrupted; Hub never silently starts a second one.
## Recovery and ownership
## Status
For agents it dispatches, Hub owns creation, reconnect recovery, output tracking, and completion. Agents you start locally are untouched.
| Status | Meaning |
| ----------------- | ---------------------------------------------- |
| Approval required | The CLI is waiting for you to approve the code |
| Connected | Online and accepting dispatch |
| Offline | Enrolled but not currently connected |
| Revoked | Access removed from Hub |
If Hub loses the create response or the daemon restarts mid-run, Hub resends the same create intent with the same execution ID. The daemon returns the existing agent instead of running the prompt twice. If an agent closes or crashes, Hub marks the run interrupted and does not silently start a second agent.
An event that arrives while a daemon is offline fails dispatch with `daemon_not_connected`. Nothing is queued for later. The event is in the project's Activity, and the trigger has to fire again. An offline daemon also blocks saving a trigger that changes its target or agent, because Hub checks that agent against it; see [Saving checks the agent against the daemon](/docs/hub/triggers#saving-checks-the-agent-against-the-daemon).
## Daemon status
Revoking from **Daemons → Revoke daemon** ends the relationship from Hub's side. The daemon keeps running your local agents.
| Status | Meaning |
| ----------------- | ---------------------------------------- |
| Approval required | The CLI is waiting for browser approval. |
| Connected | Online and connected to Hub. |
| Offline | Enrolled, but not currently connected. |
| Revoked | Access was removed from Hub. |
While the daemon is offline, you can save dashboard edits that keep the same target and agent settings, such as a prompt change. `paseo hub deploy` and direct API installs require a connected target daemon even for that edit. See [trigger validation](/docs/hub/triggers#saving-checks-the-agent-against-the-daemon).
Revoking from **Daemons → Revoke daemon** ends the relationship from Hub's side while leaving local agents running.
+68 -53
View File
@@ -1,71 +1,65 @@
---
title: Hub 中的 daemon
description: 把一台机器注册到 Hub,在配置中引用它,并了解连接后 Hub 负责哪些事情。
description: 将 Paseo daemon 注册到 Hub,授予执行权限,并在触发器中指定目标 daemon。
nav: Daemon
---
# Hub 中的 daemon {#daemons-in-hub}
daemon 是你的一台运行 Paseo daemon 的机器。把它注册到你的 Hub 组织一次,之后触发器就可以引用它。
daemon 是你运行 Paseo daemon 的一台机器。在你的 Hub 组织中注册一次,授予执行权限,然后在触发器中引用它的 slug。
## 连接 {#connect}
## 连接 daemon {#connect-a-daemon}
先在这台机器上登录:
先在该机器上登录:
```sh
paseo hub login https://hub.example.com
```
CLI 会打印一个 URL 和一个验证码,并打开你的浏览器。批准后的登录保存在 `PASEO_HOME` 下。
CLI 会输出一个 URL 和验证码,并打开浏览器。批准后,Paseo 会在 `PASEO_HOME` 下保存组织级 CLI 登录凭据。
在交互式终端中,登录流程会询问是否连接这个 daemon,并单独询问是否允许 Hub 自动化在其上运行 Agent。连接默认为是;执行权限默认为否。之后它会给出 **Triggers** 的链接,并打印 `paseo hub init`,用于以代码形式创建起步触发器。`--json` 或非 TTY 的登录只会登录。[快速开始](/docs/hub/quickstart)完整地介绍了连接和初始化。
在交互式终端中,`login` 会询问是否连接此 daemon,并单独询问是否允许 Hub 自动化运行 Agent。连接默认为是,执行权限默认为否。`--json` 和非 TTY 登录不会交互提示。
如果你之前拒绝了连接,或者这台机器已经登录过,可以单独注册 daemon:
如果你在登录时跳过了连接,可以单独注册 daemon:
```sh
paseo hub connect
```
`connect` 使用当前的登录请求一个一次性的注册 token。daemon 用它换取自己的关系凭据;你的 CLI 登录永远不会被保存为 daemon 的权限。
`connect` 使用当前登录凭据申请一个一次性注册令牌。daemon 用该令牌换取自己的关系凭据,因此你的 CLI 登录凭据永远不会作为 daemon 权限保存。
Hub 根据 daemon 的主机名生成它的初始 slug。如果该 slug 在组织中已被使用,Hub 会添加一个简短的 daemon ID 后缀。你之后可以在 Hub 中重命名 daemon。
Hub 根据主机名生成使用连字符连接的小写初始 slug,例如 `build-studio`。如果组织内已有同名 slug,Hub 会附加一个短 daemon ID 后缀。
每个 daemon 有两个标识符:一个不可变的生成 ID 和一个友好的 slug。Hub 会把 slug 规范化为用连字符连接的小写单词,因此 `Build Studio` 会变成 `build-studio`。控制台显示的、配置中引用的都是 slug。
之后可以在 Hub 中重命名 slug,不会改变不可变的 daemon ID,但需要更新引用旧 slug 的触发器。
你可以稍后修改 slug,而不改变 daemon ID。如果在某个配置生效后重命名,就需要更新该配置。
对于无人值守的设置,传入组织 API key 而不保存它:
无人值守环境中,可通过环境变量传入组织 API 密钥:
```sh
PASEO_HUB_URL=https://hub.example.com PASEO_HUB_API_KEY=paseo_pk_... paseo hub connect
```
地址的优先级依次为:显式的 `[origin]`、`PASEO_HUB_URL`、当前保存的登录,最后是 `https://hub.paseo.sh`。显式的 `--api-key <secret>` 优先于环境变量和与地址完全一致的已保存登录。
地址优先级为显式 `[origin]` 或 `--hub`、然后是 `PASEO_HUB_URL`、再是当前已保存的登录、最后是 `https://hub.paseo.sh`。显式 `--api-key <secret>` 优先于环境变量和已保存的登录。
查看与撤销:
查看状态或断开连接:
```sh
paseo hub status
paseo hub disconnect
paseo hub disconnect --force # drop local authority when Hub is unreachable
paseo hub disconnect --force # 当 Hub 不可达时清除本地凭据
```
一个 daemon 只有一个 Hub 关系。连接一个已有关系的 daemon 会被拒绝。
一台 daemon 同一时间只能连接一个 Hub 组织。试图连接已绑定其他 Hub 的 daemon 会被拒绝。
`paseo hub logout` 会移除当前的 CLI 登录。daemon 的关系是一个独立的身份,会保持连接。
在交互式终端中,退出登录时会询问是否断开注册到同一 Hub 的 daemon。如果接受,会先断开连接再删除登录,因此断开失败时你的凭据会保留。如果拒绝,只移除登录。
非交互式和 `--json` 的退出登录永远不会隐式断开 daemon:
`paseo hub logout` 会移除已保存的 CLI 登录。在交互式终端中,它会先询问是否断开连接到同一 Hub 的 daemon。在 `--json` 或非交互模式下,除非传入 `--disconnect-daemon`,否则 `logout` 不会断开 daemon:
```sh
paseo hub logout --disconnect-daemon # remove both identities
paseo hub logout --disconnect-daemon --force # drop local authority when Hub is unreachable
paseo hub logout --disconnect-daemon
paseo hub logout --disconnect-daemon --force
```
## 让 Hub 在其上运行 Agent {#let-hub-run-agents-on-it}
## 授予执行权限 {#grant-execution-permission}
注册 daemon 并不会让 Hub 在其上启动 Agent。这需要单独的 `hub.execute` 权限,登录时会询问,默认为否。你可以随时在这台机器上授予它:
注册 daemon 不会自动允许 Hub 在其上启动 Agent。需要从该机器显式授予 `hub.execute` 权限:
```sh
paseo hub permissions list
@@ -73,50 +67,71 @@ paseo hub permissions grant hub.execute
paseo hub permissions revoke hub.execute
```
在授予之前,Hub 只把该 daemon 用于身份和在线状态。Daemons 页面会把它显示为 **Connected only** 并给出授权命令,Home 清单会显示 **Cannot run agents**。授予后该权限允许做什么,见 [Hub 安全](/docs/hub/security#choose-daemon-authority)。
在授予 `hub.execute` 之前,Hub 仅追踪该 daemon 的身份和在线状态。**Daemons** 会显示为 **Connected only**,**Home** 会提示它无法运行 Agent。`hub.execute` 的权限范围见[选择 daemon 权限](/docs/hub/security#choose-daemon-authority)。
## 在配置中引用它 {#reference-it-from-configuration}
## 在触发器中指定目标 daemon {#target-a-daemon-from-a-trigger}
在 `run.target` 下引用 daemon slug 和已存在的工作目录:
```yaml
environments:
dev:
kind: daemon
name: repo-triage
on:
manual.run: {}
run:
target:
daemon: my-macbook
cwd: /Users/you/code/your-repo
agent:
provider: codex
mode: full-access
prompt: Inspect the repository status and call hub.finish_execution.
```
`daemon` 是友好的 slug。配置激活时它会解析为不可变的 daemon ID,因此不存在的 daemon 会在激活时失败,而不是等到派发时才失败。
保存或部署触发器时,`daemon` 会解析为不可变的 daemon ID。`cwd` 必须是该机器上已存在的绝对路径,Hub 不会替你克隆仓库。
`cwd` 是那台机器上的路径。Hub 不会替你克隆任何东西;该目录必须已经存在。
要让执行不影响你的 worktree,请添加一个 worktree:
如果要让每次运行在独立分支上工作,避免改动主工作树,可以添加 `worktree` 块:
```yaml
worktree:
mode: branch-off
newBranch: trigger-${{ paseo.execution.id }}
base: origin/main
name: isolate-fix
on:
manual.run: {}
run:
target:
daemon: build-server
cwd: /workspace/project
worktree:
mode: branch-off
newBranch: trigger-${{ paseo.execution.id }}
base: origin/main
agent:
provider: codex
mode: full-access
prompt: Run tests and call hub.finish_execution.
```
`${{ paseo.execution.id }}` 会渲染为本次执行的 UUID,因此每次执行都会从 `origin/main` 创建自己的分支。
`${{ paseo.execution.id }}` 会渲染为本次执行的 UUID,为每次运行基于 `origin/main` 创建唯一分支,并在重试和恢复时保持一致。参见[触发器 YAML 参考](/docs/hub/configuration/reference#target-and-worktree)和 [Git worktree](/docs/worktrees)。
[环境字段](/docs/hub/configuration/hub-yml#environments)列出了 `newBranch` 接受的值。setup 钩子和脚本见 [Git worktree](/docs/worktrees)。
## Provider 发现 {#provider-discovery}
## Hub 负责什么 {#what-hub-owns}
在 Hub 触发器编辑器中选择 daemon 和工作目录后,Hub 会向该 daemon 查询已配置的 Provider、模型、执行模式和思考选项。
对于由 Hub 派发的 Agent,Hub 负责创建、重连恢复、输出观察和完成。你自己启动的 Agent 不受影响。
Hub 支持你在 Paseo daemon 上配置的任意 Provider,包括 Claude Code、Codex、OpenCode、Pi,以及自定义或插件 Provider。
如果 Hub 丢失了创建响应,或者 daemon 在执行过程中重启,Hub 会用相同的执行 id 重新发送同一个创建意图。daemon 会返回已有的 Agent,而不是再次运行提示词。已关闭或出错的 Agent 会被记录为中断;Hub 永远不会悄悄启动第二个。
## 恢复与归属 {#recovery-and-ownership}
## 状态 {#status}
对于由 Hub 派发的 Agent,Hub 负责创建、重连恢复、输出追踪和完成状态。你在本地手动启动的 Agent 不会受到影响。
| 状态 | 含义 |
| ----------------- | ------------------------ |
| Approval required | CLI 正在等待你批准验证码 |
| Connected | 在线并接受派发 |
| Offline | 已注册但当前未连接 |
| Revoked | 已从 Hub 移除访问权限 |
如果 Hub 丢失了创建响应,或者 daemon 在运行中途重启,Hub 会用同一个执行 ID 重新发送相同的创建意图。daemon 会返回已有的 Agent,而不会把提示词再运行一次。如果 Agent 意外关闭或出错,Hub 会将此次运行标记为已中断,不会静默启动第二个 Agent。
daemon 离线期间到达的事件会派发失败,并报告 `daemon_not_connected`。不会排队等待之后处理。事件会出现在项目的 Activity 中,触发器需要再次触发。离线的 daemon 还会阻止保存修改了目标或 Agent 的触发器,因为 Hub 会根据它检查该 Agent;参见[保存时会根据 daemon 检查 Agent](/docs/hub/triggers#saving-checks-the-agent-against-the-daemon)。
## Daemon 状态 {#daemon-status}
从 **Daemons → Revoke daemon** 撤销会从 Hub 一侧结束这段关系。daemon 会继续运行你的本地 Agent。
| 状态 | 含义 |
| ----------------- | ------------------------------------ |
| Approval required | CLI 正在等待你在浏览器中批准验证码。 |
| Connected | 在线且已连接到 Hub。 |
| Offline | 已注册,但当前未连接。 |
| Revoked | 已在 Hub 中撤销访问权限。 |
daemon 离线时,只要目标和 Agent 设置不变,你仍可在控制台保存修改,例如只改提示词。即使只改提示词,通过 CLI 部署或直接通过 API 安装也要求目标 daemon 已连接。请参阅[触发器校验](/docs/hub/triggers#saving-checks-the-agent-against-the-daemon)。
在 **Daemons → Revoke daemon** 中撤销连接会从 Hub 侧终止关系,同时保持本地 Agent 继续运行。
+32 -34
View File
@@ -1,8 +1,8 @@
---
title: Hub FAQ
description: Common questions about projects, connections, configuration, and daemons in Paseo Hub.
description: Common questions about triggers, providers, integrations, daemons, and replies in Paseo Hub.
nav: FAQ
order: 78
order: 84
category: Hub
---
@@ -10,52 +10,50 @@ category: Hub
## Do I need Hub to use Paseo?
No. Paseo runs agents on your machines without it. Hub adds what a single daemon cannot do on its own: starting agents from external activity, versioned configuration, a shared record of what ran, and team access.
No. Paseo runs agents on your machines without Hub. Hub adds event triggers, recurring schedules, inbound webhooks, shared run history, and team access on top of your daemons.
## Can one organization connect several GitHub organizations?
## Which agent providers can Hub run?
Yes. Connections belong to the organization and there is no limit on how many you add. Each gets its own slug.
Hub runs any provider configured on your connected Paseo daemon, including Claude Code, Codex, OpenCode, Pi, and custom or plugin providers. When you create or edit a trigger, Hub queries that daemon for its available providers, models, execution modes, and thinking options.
## How should I split my work into projects?
## Where do triggers live?
The way you already split it: one per product, one per team, or one per repository. A project owns one set of environments and triggers, so anything that should be configured and deployed together belongs in the same project.
You can create and edit triggers directly in the Hub dashboard under **Triggers**, or keep them as self-contained `.paseo/triggers/*.yml` files in your repository and deploy them with `paseo hub deploy`. Both paths use the same YAML schema and validation.
Projects share the organization's connections and daemons, so a new project does not mean connecting GitHub or registering a daemon again.
## Can one organization connect multiple GitHub, Linear, Slack, or Discord workspaces?
## Can two projects watch the same repository?
Yes. Both run. Repositories are not owned by a project.
## Can the configuration live somewhere other than the repository being watched?
Yes. `filters.repo` can name any repository the organization can reach, so a private repository can hold the `.paseo` bundle for workflows that watch public repositories. Protect push access because the bundle selects the organization's connections, daemons, agents, and outputs.
## Where do triggers go now?
Each trigger and its ordered steps live in one direct `.paseo/workflows/*.yml` file. `hub.yml` contains only named environments and agents. Hub rejects monolithic `triggers` configuration instead of translating it.
## Can I edit configuration in the dashboard?
Yes, with a manual source. A project using a GitHub source is read-only in the dashboard, since the repository is the source of truth. Switching to manual copies the active revision into the editor and stops syncing.
Yes. Integrations belong to the organization under **Integrations**, and each connected workspace, server, or GitHub installation gets its own slug. Set `connection` on a trigger event to target one specific integration.
## Who can trigger an agent?
Only the users listed in a trigger's `from_users`. It is required and cannot be empty.
GitHub, Slack, and Discord triggers accept `from_users: ["*"]`, the value the dashboard saves for **Audience → Everyone**. To limit who can trigger a run, list the allowed logins or user IDs in `from_users`.
## What happens if the daemon is offline?
For Linear comments and assignments, **Everyone** matches no users. Choose **Specific people** and enter the allowed Linear user UUIDs in **User IDs**. See [trigger filters](/docs/hub/triggers#filters).
Dispatch fails and the event is recorded as failed. Nothing is queued, so trigger it again once the daemon is back.
`linear.issue_entered_scope` requires `filters.project` and can omit `from_users`. Inbound webhooks authenticate callers with a Bearer secret (`whsec_...`), and schedules fire on Hub's own clock.
## Can an agent reply back to GitHub, Linear, Slack, or Discord?
Hub grants the `reply` tool when the event has an issue, pull request, or thread to reply to. A `github.push` event has no reply destination.
Add `run.outputs` to set `max` or `required: true`, and tell the agent to call `reply` and `finish_execution` in `run.prompt`. When Hub runs over HTTPS, replies include an **Open in Paseo** link for signed-in organization members.
## Can a schedule or webhook post to Slack or Discord?
Yes. Add [`run.tools`](/docs/hub/tools) (or configure **Integration tools** in the dashboard) to grant any trigger scoped `read` or `post` tools for explicit Slack or Discord channel IDs.
## What happens when a daemon is offline?
When Hub accepts a provider event or inbound webhook while the target daemon is offline, Hub keeps the run queued and retries dispatch until its `max_runtime` deadline expires. If the daemon reconnects in time, the queued run starts automatically, so resending the event can start a duplicate run.
Wait for **Activity** to show a terminal failure before sending a new event. Scheduled triggers continue firing at future occurrences and skip overlapping ticks while an earlier run is active.
## Does logging out disconnect my daemon?
No. The stored CLI login is a human organization credential; the enrolled daemon has its own relationship credential. Interactive `paseo hub logout` offers to disconnect a daemon related to the same Hub. Declining is normal, and JSON or noninteractive logout never disconnects unless you pass `--disconnect-daemon`.
No. The CLI login is a human credential stored under `PASEO_HOME`, while an enrolled daemon holds its own relationship credential.
## Can an agent reply back to Slack or Discord?
Interactive `paseo hub logout` offers to disconnect a daemon connected to the same Hub before deleting the login. Non-interactive and `--json` logout never disconnect the daemon unless you pass `--disconnect-daemon`.
Yes. Put `allow_outputs` on the step and tell the agent to call `hub.reply` in the prompt. [Tell the agent which tool to call](/docs/hub/workflows#tell-the-agent-which-tool-to-call) shows the prompting; reply limits and `required` are in the [output capability reference](/docs/hub/configuration/hub-yml#output-capabilities).
## Can I use Hub without GitHub?
GitHub has no reply capability; give the step a [`github` block](/docs/hub/github) and the agent acts through the `gh` CLI.
## Can I use it without GitHub?
Yes. A project with a manual configuration and a Discord or Slack connection works fine. GitHub is only needed if you want configuration synced from a repository.
Yes. Hub works with Linear, Slack, Discord, schedules, and inbound webhooks without connecting GitHub. GitHub is needed only for GitHub triggers or [`run.github`](/docs/hub/github) repository tokens.
+32 -34
View File
@@ -1,59 +1,57 @@
---
title: Hub 常见问题
description: 关于 Paseo Hub 中项目、连接、配置和 daemon 的常见问题。
description: 关于 Paseo Hub 中触发器、Provider、集成、daemon 和回复的常见问题。
nav: 常见问题
---
# Hub 常见问题 {#hub-faq}
## 使用 Paseo 需要 Hub 吗? {#do-i-need-hub-to-use-paseo}
## 使用 Paseo 必须搭配 Hub 吗? {#do-i-need-hub-to-use-paseo}
不需要。没有 Hub,Paseo 也能在你的机器上运行 Agent。Hub 增加的是单个 daemon 自身做不到的事:由外部活动启动 Agent、版本化的配置、共享的运行记录,以及团队访问。
不需要。没有 Hub,Paseo 也可以在你的机器上运行 Agent。Hub 在你的 daemon 之上增加了事件触发器、周期性定时任务、入站 webhook、共享运行历史和团队访问能力。
## 一个组织可以连接多个 GitHub 组织吗? {#can-one-organization-connect-several-github-organizations}
## Hub 可以运行哪些 Agent Provider? {#which-agent-providers-can-hub-run}
可以。连接属于组织,添加数量没有上限。每个连接都有自己的 slug。
Hub 可以运行你已连接的 Paseo daemon 上配置的任意 Provider,包括 Claude Code、Codex、OpenCode、Pi,以及自定义或插件 Provider。创建或编辑触发器时,Hub 会向该 daemon 查询可用的 Provider、模型、执行模式和思考选项。
## 应该如何把工作划分为项目? {#how-should-i-split-my-work-into-projects}
## 触发器保存在哪里? {#where-do-triggers-live}
按你现有的划分方式:每个产品一个、每个团队一个,或每个仓库一个。一个项目拥有一组环境和触发器,因此需要一起配置和部署的内容应该放在同一个项目中。
你可以直接在 Hub 控制台的 **Triggers** 中创建和编辑触发器,也可以将它们作为自包含的 `.paseo/triggers/*.yml` 文件保存在仓库中,并通过 `paseo hub deploy` 部署。两种方式使用相同的 YAML 结构和校验。
项目共享组织的连接和 daemon,所以新建项目并不意味着要重新连接 GitHub 或重新注册 daemon。
## 一个组织可以连接多个 GitHub、Linear、Slack 或 Discord 工作区吗? {#can-one-organization-connect-multiple-github-linear-slack-or-discord-workspaces}
## 两个项目可以监听同一个仓库吗? {#can-two-projects-watch-the-same-repository}
可以,两个都会运行。仓库不归某个项目所有。
## 配置可以放在被监听的仓库之外吗? {#can-the-configuration-live-somewhere-other-than-the-repository-being-watched}
可以。`filters.repo` 可以指定组织能访问的任意仓库,因此一个私有仓库可以保存监听公开仓库的 workflow 的 `.paseo` 配置包。请保护好推送权限,因为配置包决定了组织的连接、daemon、Agent 和输出。
## 现在触发器放在哪里? {#where-do-triggers-go-now}
每个触发器及其有序的 step 都放在一个直接位于 `.paseo/workflows/*.yml` 的文件中。`hub.yml` 只包含命名的环境和 Agent。Hub 会拒绝整体式的 `triggers` 配置,而不是转换它。
## 可以在控制台中编辑配置吗? {#can-i-edit-configuration-in-the-dashboard}
可以,前提是使用手动来源。使用 GitHub 来源的项目在控制台中是只读的,因为仓库才是唯一的事实来源。切换到手动会把当前生效的版本复制到编辑器中,并停止同步。
可以。集成归组织所有,位于 **Integrations** 下,每个已连接的工作区、服务器或 GitHub 安装都有自己的 slug。在触发器事件上设置 `connection` 即可指定某一个集成。
## 谁可以触发 Agent? {#who-can-trigger-an-agent}
只有触发器 `from_users` 中列出的用户。该字段是必填的,不能为空。
GitHub、Slack 和 Discord 触发器支持 `from_users: ["*"]`,这是控制台为 **Audience → Everyone** 保存的值。如需限制谁能触发运行,请在 `from_users` 中列出允许的登录名或用户 ID。
## 如果 daemon 离线会怎样? {#what-happens-if-the-daemon-is-offline}
对于 Linear 评论和分配事件,**Everyone** 无法匹配用户。请选择 **Specific people**,并在 **User IDs** 中输入允许的 Linear 用户 UUID。请参阅[触发器过滤条件](/docs/hub/triggers#filters)。
派发失败,事件会被记录为失败。不会排队,所以请在 daemon 恢复后重新触发。
`linear.issue_entered_scope` 要求设置 `filters.project` 且可以省略 `from_users`。入站 webhook 通过 Bearer 密钥(`whsec_...`)验证调用方,定时任务则按 Hub 自己的时钟触发。
## Agent 可以回复到 GitHub、Linear、Slack 或 Discord 吗? {#can-an-agent-reply-back-to-github-linear-slack-or-discord}
当事件有关联的 issue、Pull Request 或讨论串可供回复时,Hub 会授予 `reply` 工具。`github.push` 事件没有回复目标。
添加 `run.outputs` 可设置 `max` 或 `required: true`,并在 `run.prompt` 中指示 Agent 调用 `reply` 和 `finish_execution`。当 Hub 运行在 HTTPS 下时,回复会为已登录的组织成员附带 **Open in Paseo** 链接。
## 定时任务或 webhook 可以发送到 Slack 或 Discord 吗? {#can-a-schedule-or-webhook-post-to-slack-or-discord}
可以。添加 [`run.tools`](/docs/hub/tools)(或在控制台中配置 **Integration tools**),即可为任意触发器授予针对显式 Slack 或 Discord 频道 ID 的受控 `read` 或 `post` 工具。
## daemon 离线时会发生什么? {#what-happens-when-a-daemon-is-offline}
如果目标 daemon 离线时 Hub 接受了 Provider 事件或入站 webhook,Hub 会将该运行保留在队列中并重试派发,直到达到 `max_runtime` 截止时间。如果 daemon 在截止时间前重新上线,排队中的运行会自动启动,因此重新发送事件可能会造成重复运行。
请等到 **Activity** 显示该运行已进入终态失败后再发送新事件。定时触发器会在未来计划时间继续触发,并在前一次运行活跃时跳过重叠的计划。
## 退出登录会断开我的 daemon 吗? {#does-logging-out-disconnect-my-daemon}
不会。保存的 CLI 登录是一个人员的组织凭据;已注册的 daemon 有自己的关系凭据。交互式的 `paseo hub logout` 会询问是否断开与同一 Hub 相关的 daemon。拒绝是正常的;除非你传入 `--disconnect-daemon`,JSON 或非交互式的退出登录永远不会断开 daemon。
不会。CLI 登录是保存在 `PASEO_HOME` 下的个人凭据,而已注册的 daemon 持有自己的关系凭据。
## Agent 可以回复到 Slack 或 Discord 吗? {#can-an-agent-reply-back-to-slack-or-discord}
交互式 `paseo hub logout` 会在删除登录前询问是否断开连接到同一 Hub 的 daemon。非交互式和 `--json` 退出登录除非传入 `--disconnect-daemon`,否则不会断开 daemon。
可以。在 step 上设置 `allow_outputs`,并在提示词中告诉 Agent 调用 `hub.reply`。[告诉 Agent 调用哪个工具](/docs/hub/workflows#tell-the-agent-which-tool-to-call)展示了提示词写法;回复次数限制和 `required` 见[输出能力参考](/docs/hub/configuration/hub-yml#output-capabilities)。
## 不使用 GitHub 也能用 Hub 吗? {#can-i-use-hub-without-github}
GitHub 没有回复能力;请给 step 添加 [`github` 块](/docs/hub/github),Agent 会通过 `gh` CLI 执行操作。
## 不用 GitHub 可以吗? {#can-i-use-it-without-github}
可以。使用手动配置并连接 Discord 或 Slack 的项目可以正常工作。只有当你想从仓库同步配置时才需要 GitHub。
可以。不连接 GitHub 也可以使用 Linear、Slack、Discord、定时任务和入站 webhook。只有在需要 GitHub 触发器或 [`run.github`](/docs/hub/github) 仓库令牌时才需要 GitHub。
+61 -46
View File
@@ -1,76 +1,91 @@
---
title: GitHub access
description: Grant one workflow step a scoped GitHub token and git setup.
description: Grant a Hub trigger a scoped GitHub installation token and isolated git configuration.
nav: GitHub access
order: 65
order: 72
category: Hub
---
# GitHub access
A trigger grants no GitHub credential. Put a `github` block on the step that needs repository authority:
A trigger grants no `GH_TOKEN` or git push authority by default. Add a `run.github` block to any trigger whose agent needs `git` or `gh` access to push branches, open pull requests, or edit issues:
```yaml
name: implement-request
on: github.issue_comment
max_runtime: 2h
filters:
repo: example/project
contains: "@paseo"
from_users: [maintainer]
steps:
- id: implement
environment: development
max_runtime: 90m
idle_timeout: 10m
agent: codex
github:
connection: example-github
repositories: [example/project]
permissions:
contents: write
pull_requests: write
prompt:
- text: |
Implement the request, push a branch, and open a pull request with gh.
Call hub.finish_execution when done.
${{ paseo.prompt }}
on:
github.issue_comment_created:
connection: acme-github
filters:
repo: acme/project
contains: "@paseo"
from_users: [maintainer]
run:
target:
daemon: devbox
cwd: /workspace/project
worktree:
mode: branch-off
newBranch: trigger-${{ paseo.execution.id }}
base: origin/main
agent:
provider: codex
mode: full-access
max_runtime: 90m
idle_timeout: 10m
github:
connection: acme-github
repositories: [acme/project]
permissions:
contents: write
pull_requests: write
prompt: |
Implement the request, push a branch, and open a pull request with gh.
Reply with the PR link using reply, then call finish_execution.
<user-prompt>
${{ paseo.prompt }}
</user-prompt>
```
The agent can use `git` and `gh` within the declared repositories and permissions. See [agent continuation](/docs/hub/configuration/hub-yml#agent-continuation) for the token lifecycle when requests continue an agent.
`run.github` works on any trigger source, including Linear, Slack, Discord, schedules, and webhooks.
## Fields
| Field | Notes |
| -------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| `connection` | Project GitHub connection slug. |
| `repositories` | Repositories the token can reach. On a GitHub-triggered run, this defaults to the triggering repository. Required for other providers. |
| `permissions` | Installation-token permissions such as `contents`, `pull_requests`, and `issues`. Defaults to `contents: read`. |
| `duration` | Positive token lifetime up to `1h`. Defaults to `1h`, GitHub's maximum. |
| Field | Notes |
| -------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| `connection` | GitHub integration slug from **Integrations**. |
| `repositories` | Repositories the token can reach. On a GitHub-triggered run, this defaults to the triggering repository. Required for other events. |
| `permissions` | Installation-token permissions such as `contents`, `pull_requests`, and `issues` (`read`, `write`, or `admin`). Defaults to `contents: read`. |
| `duration` | Positive token lifetime up to `1h`. Defaults to `1h`, GitHub's maximum. |
Requested authority cannot exceed the GitHub App installation. Activation and dispatch fail clearly when the connection, repository, or permissions cannot be resolved.
Requested permissions cannot exceed what the GitHub App installation allows.
When you save or deploy a trigger, Hub validates the `run.github` schema, any GitHub event filters (`on.github.*`), and the agent configuration. Hub looks up `run.github.connection` and mints the installation token when the run launches, so a nonexistent slug, unreachable repository, or excess permission fails at launch rather than at deploy time.
## Agent environment
Hub supplies `GH_TOKEN` and process-scoped git configuration through environment variables:
When `run.github` is present, Hub mints a short-lived GitHub App installation token and injects `GH_TOKEN` plus process-scoped git configuration into the agent environment:
- Commits use the App bot login as `user.name` and `<app-id>+<bot-login>@users.noreply.github.com` as `user.email`.
- `git@github.com:` and `ssh://git@github.com/` remotes are rewritten to HTTPS.
- `gh auth git-credential` handles GitHub credentials for the step.
- User-global and system git configuration are ignored, and terminal credential prompts are disabled.
- The daemon host's git identity and credentials are not read or changed.
- `git@github.com:` and `ssh://git@github.com/` remotes rewrite to HTTPS.
- `gh auth git-credential` supplies credentials for git operations.
- User-global and system git configuration are ignored, and interactive credential prompts are disabled.
- The daemon host's own git identity and SSH credentials are not read or changed.
`GH_TOKEN` and Hub's git configuration variables are reserved when a step has a `github` block; workflow `env` cannot replace them.
`GH_TOKEN` and Hub's git configuration variables are reserved when `run.github` is configured, so `run.env` cannot overwrite them.
## Keep authority on the worker
## Continuation and token lifecycle
A classifier can read untrusted request text without GitHub authority. Put the `github` block only on the later branch that makes a change. [Workflow routing](/docs/hub/workflows#route-from-a-classifier) shows the ordered classifier/worker shape.
With `run.github` or a connection token in `run.env`, follow-ups on an active continuing agent share the leased token until all active requests finish. Hub then revokes leased tokens, and the next arrival starts a fresh agent with a new token. For scheduled or webhook triggers with temporary GitHub tokens, prefer `continuation: { mode: new }`.
Connection values for other integrations remain explicit step environment values:
## Other connection values
You can pass values from other organization connections into an agent's environment explicitly with `run.env`:
```yaml
env:
SOME_TOKEN: "${{ paseo.connections.some-connection.token }}"
run:
env:
SOME_TOKEN: "${{ paseo.connections.some-connection.token }}"
```
Hub resolves the value when it prepares the agent's environment. See [Hub security](/docs/hub/security) for provider and host boundaries.
Hub resolves the expression when preparing the agent environment. See [Hub security](/docs/hub/security) for host and permission boundaries.

Some files were not shown because too many files have changed in this diff Show More