Skip to content

Open-source AI teammates in Slack, Teams, Discord, Telegram and Mattermost. Self-host it, with any agent harness and any model.

feat(gateway-ui): server-driven reference type metadata in forms

raullopez-sandbox0150eca37476
diff --git a/gateway/src/data/api.ts b/gateway/src/data/api.ts
index 655e3472b..5d6ca9106 100644
--- a/gateway/src/data/api.ts
+++ b/gateway/src/data/api.ts
@@ -897,6 +897,48 @@ export interface ReferenceTypeInfo {
display_name: string;
instructions: string;
value_schema: Record<string, unknown>;
+ value_hint: string;
+ is_builtin: boolean;
+ // Null for a built-in. A user-defined type names its author wherever it is
+ // offered: its instructions are prose every agent in the room is told to follow.
+ owner_id: string | null;
+ owner_name: string | null;
+}
+
+export interface ReferenceTypeDetail {
+ type: string;
+ display_name: string;
+ instructions: string;
+ value_schema: Record<string, unknown>;
+ value_hint: string;
+ is_builtin: boolean;
+ owner_id: string;
+ owner_name: string | null;
+ read_visibility: "public" | "private";
+ write_visibility: "public" | "private";
+ shadowed_by_builtin: boolean;
+ created_at: string;
+}
+
+export interface ReferenceTypeCreateInput {
+ type: string;
+ display_name: string;
+ instructions: string;
+ value_hint: string;
+ read_visibility: "public" | "private";
+ write_visibility: "public" | "private";
+}
+
+export interface ReferenceTypeUpdateInput {
+ display_name?: string;
+ instructions?: string;
+ value_hint?: string;
+ read_visibility?: "public" | "private";
+ write_visibility?: "public" | "private";
+}
+
+export interface ReferenceTypeDeleteResult {
+ deleted_type: string;
}
export interface ReferenceDetail {
@@ -913,6 +955,9 @@ export interface ReferenceDetail {
attached_rooms_count: number;
packages: string[];
created_at: string;
+ // Resolved server-side and unfiltered by the type's visibility. Null when
+ // the slug resolves to no type at all.
+ type_display_name: string | null;
}
export interface ReferenceCreateInput {
@@ -989,6 +1034,42 @@ export async function fetchReferenceTypes(): Promise<ReferenceTypeInfo[] | null>
return fetchJson<ReferenceTypeInfo[]>("/references/reference-types");
}
+export async function fetchOwnedReferenceTypes(): Promise<
+ ReferenceTypeDetail[] | null
+> {
+ return fetchJson<ReferenceTypeDetail[]>("/references/reference-types/owned");
+}
+
+export async function createReferenceType(
+ input: ReferenceTypeCreateInput,
+): Promise<ReferenceTypeDetail> {
+ return jsonRequest<ReferenceTypeDetail>(
+ "/references/reference-types",
+ "POST",
+ input,
+ );
+}
+
+export async function updateReferenceType(
+ type: string,
+ input: ReferenceTypeUpdateInput,
+): Promise<ReferenceTypeDetail> {
+ return jsonRequest<ReferenceTypeDetail>(
+ `/references/reference-types/${type}`,
+ "PATCH",
+ input,
+ );
+}
+
+export async function deleteReferenceType(
+ type: string,
+): Promise<ReferenceTypeDeleteResult> {
+ return jsonRequest<ReferenceTypeDeleteResult>(
+ `/references/reference-types/${type}`,
+ "DELETE",
+ );
+}
+
export async function fetchReferences(): Promise<ReferenceDetail[] | null> {
return fetchJson<ReferenceDetail[]>("/references");
}
diff --git a/gateway/src/data/hooks.ts b/gateway/src/data/hooks.ts
index 5a05d9317..e5db72b35 100644
--- a/gateway/src/data/hooks.ts
+++ b/gateway/src/data/hooks.ts
@@ -16,6 +16,7 @@ import {
type EcosystemGraphData,
type PackageDetail,
type ReferenceDetail,
+ type ReferenceTypeDetail,
type ReferenceTypeInfo,
type ResourceRoom,
type RoomDetail,
@@ -42,6 +43,7 @@ import {
fetchPackageReferences,
fetchPackageRooms,
fetchPackages,
+ fetchOwnedReferenceTypes,
fetchReferenceRooms,
fetchReferenceTypes,
fetchReferences,
@@ -179,6 +181,10 @@ export function useReferenceTypes(): UseQueryResult<ReferenceTypeInfo[]> {
return useQuery(fetchReferenceTypes);
}
+export function useOwnedReferenceTypes(): UseQueryResult<ReferenceTypeDetail[]> {
+ return useQuery(fetchOwnedReferenceTypes);
+}
+
export function useLinkedRooms(
roomId: string | undefined,
): UseQueryResult<LinkedRoomDetail[]> {
diff --git a/gateway/src/pages/resources/CreateReferenceDialog.tsx b/gateway/src/pages/resources/CreateReferenceDialog.tsx
index a29db5968..89706cb0b 100644
--- a/gateway/src/pages/resources/CreateReferenceDialog.tsx
+++ b/gateway/src/pages/resources/CreateReferenceDialog.tsx
@@ -15,8 +15,7 @@ import { createReference } from "../../data/api";
import { AccessSelect } from "../../components/AccessControls";
import { type AccessLevel, fromAccessLevel } from "../../data/visibility";
import { useReferenceTypes } from "../../data/hooks";
-import JsonValueForm from "./value_forms/JsonValueForm";
-import { VALUE_FORMS } from "./value_forms";
+import UrlsValueForm from "./value_forms/UrlsValueForm";
interface Props {
open: boolean;
@@ -72,7 +71,8 @@ export default function CreateReferenceDialog({ open, onClose, onCreated }: Prop
}
};
- const ValueForm = type ? (VALUE_FORMS[type] ?? JsonValueForm) : null;
+ // The slug was picked from this very list, so it always resolves.
+ const selectedType = (types ?? []).find((t) => t.type === type);
const canSubmit =
!!type && name.trim().length > 0 && description.trim().length > 0 && !submitting;
@@ -93,13 +93,20 @@ export default function CreateReferenceDialog({ open, onClose, onCreated }: Prop
>
{(types ?? []).map((t) => (
<MenuItem key={t.type} value={t.type}>
- {t.display_name}
+ {t.is_builtin
+ ? t.display_name
+ : `${t.display_name} — by ${t.owner_name ?? t.owner_id}`}
</MenuItem>
))}
</TextField>
- {ValueForm && (
- <ValueForm value={value} onChange={setValue} disabled={submitting} />
+ {selectedType && (
+ <UrlsValueForm
+ value={value}
+ onChange={setValue}
+ disabled={submitting}
+ helperText={selectedType.value_hint}
+ />
)}
<TextField
diff --git a/gateway/src/pages/resources/ReferenceDetailPage.tsx b/gateway/src/pages/resources/ReferenceDetailPage.tsx
index 63dececc3..43a8cd1a2 100644
--- a/gateway/src/pages/resources/ReferenceDetailPage.tsx
+++ b/gateway/src/pages/resources/ReferenceDetailPage.tsx
@@ -31,7 +31,7 @@ import { EM_DASH, MONO_SX, formatDateTime } from "../../theme/hootFormat";
import DeleteResourceDialog from "./DeleteResourceDialog";
import ResourceAttachmentsSection from "./ResourceAttachmentsSection";
import JsonValueForm from "./value_forms/JsonValueForm";
-import { VALUE_FORMS } from "./value_forms";
+import UrlsValueForm from "./value_forms/UrlsValueForm";
export default function ReferenceDetailPage() {
const { id } = useParams<{ id: string }>();
@@ -79,7 +79,9 @@ export default function ReferenceDetailPage() {
);
}
- const typeSpec = (types ?? []).find((t) => t.type === ref.type);
+ // Visibility-filtered, so it may miss a type this reference legitimately
+ // has. Its only job is the value hint; every label comes from the server.
+ const visibleTypeSpec = (types ?? []).find((t) => t.type === ref.type);
const canMutate =
!!user && (user.id === ref.owner_id || user.role === "admin");
@@ -95,16 +97,20 @@ export default function ReferenceDetailPage() {
<Typography variant="h5" sx={{ flexGrow: 1 }}>
{ref.name || "Reference"}
</Typography>
- <Chip label={typeSpec?.display_name ?? ref.type} size="small" />
+ <Chip
+ label={ref.type_display_name ?? `${ref.type} (unknown type)`}
+ size="small"
+ />
<AccessChip pair={ref} />
</Stack>
<Stack spacing={4}>
- <RefInfoSection ref_={ref} typeLabel={typeSpec?.display_name} />
+ <RefInfoSection ref_={ref} />
<Divider />
<EditFieldsSection
ref_={ref}
canMutate={canMutate}
+ valueHint={visibleTypeSpec?.value_hint}
onSaved={(updated) => setRef(updated)}
/>
<Divider />
@@ -131,19 +137,16 @@ export default function ReferenceDetailPage() {
);
}
-function RefInfoSection({
- ref_,
- typeLabel,
-}: {
- ref_: ReferenceDetail;
- typeLabel: string | undefined;
-}) {
+function RefInfoSection({ ref_ }: { ref_: ReferenceDetail }) {
return (
<Stack spacing={1}>
<Typography variant="overline" sx={{ color: "text.secondary", display: "block" }}>
Info
</Typography>
- <InfoLine label="Type" value={typeLabel ?? ref_.type} />
+ <InfoLine
+ label="Type"
+ value={ref_.type_display_name ?? `${ref_.type} (unknown type)`}
+ />
{ref_.owner_name ? (
<InfoLine label="Owner" value={ref_.owner_name} />
) : (
@@ -182,10 +185,12 @@ function InfoLine({
function EditFieldsSection({
ref_,
canMutate,
+ valueHint,
onSaved,
}: {
ref_: ReferenceDetail;
canMutate: boolean;
+ valueHint: string | undefined;
onSaved: (updated: ReferenceDetail) => void;
}) {
const [name, setName] = useState(ref_.name);
@@ -195,6 +200,7 @@ function EditFieldsSection({
const [value, setValue] = useState<Record<string, unknown>>(ref_.value);
const [saving, setSaving] = useState(false);
const [error, setError] = useState<string | null>(null);
+ const [valueValid, setValueValid] = useState(true);
const dirty = useMemo(
() =>
@@ -225,7 +231,9 @@ function EditFieldsSection({
}
};
- const ValueForm = VALUE_FORMS[ref_.type] ?? JsonValueForm;
+ // Keyed on the value's shape, not on whether the type resolves: every type
+ // shares the URL shape, and the type may simply not be visible to this user.
+ const isUrlsValue = Array.isArray(value.urls);
return (
<Stack spacing={2}>
@@ -256,11 +264,24 @@ function EditFieldsSection({
minRows={6}
helperText="Sent to agents on connect. Not shown in lists."
/>
- <ValueForm
- value={value}
- onChange={setValue}
- disabled={!canMutate || saving}
- />
+ {isUrlsValue ? (
+ <UrlsValueForm
+ value={value}
+ onChange={setValue}
+ disabled={!canMutate || saving}
+ helperText={
+ valueHint ??
+ "This reference's type is not visible to you. Enter one URL per line."
+ }
+ />
+ ) : (
+ <JsonValueForm
+ value={value}
+ onChange={setValue}
+ disabled={!canMutate || saving}
+ onValidityChange={setValueValid}
+ />
+ )}
<AccessSelect
value={access}
onChange={setAccess}
@@ -272,7 +293,7 @@ function EditFieldsSection({
<Button
variant="contained"
onClick={handleSave}
- disabled={!canMutate || !dirty || saving}
+ disabled={!canMutate || !dirty || saving || !valueValid}
startIcon={saving ? <CircularProgress size={16} /> : undefined}
>
Save
diff --git a/gateway/src/pages/resources/value_forms/JsonValueForm.tsx b/gateway/src/pages/resources/value_forms/JsonValueForm.tsx
index ba086bc84..396fc79ec 100644
--- a/gateway/src/pages/resources/value_forms/JsonValueForm.tsx
+++ b/gateway/src/pages/resources/value_forms/JsonValueForm.tsx
@@ -1,12 +1,24 @@
-import { Alert, Stack, TextField } from "@mui/material";
+import { Alert, Stack, TextField, Typography } from "@mui/material";
import { useEffect, useState } from "react";
import type { ValueFormProps } from "./types";
+interface Props extends ValueFormProps {
+ onValidityChange: (valid: boolean) => void;
+}
+
/**
- * Fallback editor for reference types that have no dedicated form component
- * registered. Accepts raw JSON and parses on every keystroke.
+ * Raw editor for a value bag that is not `{urls: string[]}`. Every reference
+ * type shares the URL shape, so this is reached only by a legacy row. Parses
+ * on every keystroke and reports validity upward: the parent holds the last
+ * successfully parsed value, so without that signal an invalid edit would
+ * submit the stale one.
*/
-export default function JsonValueForm({ value, onChange, disabled }: ValueFormProps) {
+export default function JsonValueForm({
+ value,
+ onChange,
+ disabled,
+ onValidityChange,
+}: Props) {
const [text, setText] = useState(() => JSON.stringify(value ?? {}, null, 2));
const [error, setError] = useState<string | null>(null);
@@ -22,13 +34,18 @@ export default function JsonValueForm({ value, onChange, disabled }: ValueFormPr
const parsed = raw.trim() === "" ? {} : JSON.parse(raw);
onChange(parsed as Record<string, unknown>);
setError(null);
+ onValidityChange(true);
} catch (e) {
setError(e instanceof Error ? e.message : "Invalid JSON");
+ onValidityChange(false);
}
};
return (
<Stack spacing={1}>
+ <Typography variant="caption" color="text.secondary">
+ This value is not a list of URLs, so it is shown as raw JSON.
+ </Typography>
<TextField
label="Value (JSON)"
multiline
diff --git a/gateway/src/pages/resources/value_forms/index.tsx b/gateway/src/pages/resources/value_forms/index.tsx
deleted file mode 100644
index c405a73d5..000000000
--- a/gateway/src/pages/resources/value_forms/index.tsx
+++ /dev/null
@@ -1,40 +0,0 @@
-import type { ComponentType } from "react";
-import UrlsValueForm from "./UrlsValueForm";
-import type { ValueFormProps } from "./types";
-
-interface BuiltInProps extends ValueFormProps {
- // No extra props for the built-in variants.
-}
-
-/**
- * Map of reference type → form component for editing its `value` bag.
- * Add a new entry when a new reference type is added in the backend registry.
- * When a type is not registered here, the dialog falls back to a generic
- * JSON textarea so the user can still create the reference manually.
- */
-export const VALUE_FORMS: Record<string, ComponentType<BuiltInProps>> = {
- google_drive: (props) => (
- <UrlsValueForm
- {...props}
- helperText="Paste links to Google Drive documents or folders."
- />
- ),
- confluence: (props) => (
- <UrlsValueForm
- {...props}
- helperText="Paste links to Confluence pages or spaces."
- />
- ),
- github: (props) => (
- <UrlsValueForm
- {...props}
- helperText="Paste links to GitHub repositories (e.g. https://github.com/org/repo)."
- />
- ),
- jira: (props) => (
- <UrlsValueForm
- {...props}
- helperText="Paste links to Jira projects, issues, or boards (e.g. https://your-org.atlassian.net/browse/PROJ-123)."
- />
- ),
-};