feat(ui): add shared knowledge lifecycle demo in Memory

This commit is contained in:
Ishaan Jaff 2026-10-20 10:34:51 -07:00
parent 2c6b280755
commit 8072b0dadc
No known key found for this signature in database
18 changed files with 2521 additions and 5 deletions

Binary file not shown.

After

Width:  |  Height:  |  Size: 194 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 209 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 228 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 227 KiB

View file

@ -0,0 +1,41 @@
# Shared knowledge demo
A four-step prototype inside LiteLLM's existing dashboard, available to admins from **Agentic → Memory → Shared knowledge demo**.
1. **Define scope:** enable categories for user systems and operator systems.
2. **Capture a memo:** save an agent's researched finding with a title, summary, guidance, and source evidence.
3. **Review and reuse:** review a proposed correction, publish a new version, load it in another session, and record a helpful outcome. Try an unsupported correction to see rejection preserve the published version.
4. **Learn and curate:** promote frequently useful guidance to a skill, archive a superseded workaround, and retain the rare but useful Bazel fix.
The four numbered PNG files show this sequence in the real dashboard shell. The Memory before/after images highlight the new entry point. The before image uses the static dashboard shipped at the base revision; both use the same empty Memory fixture and URL.
## Run locally
Use the Node and npm versions required by `package.json`. From `ui/litellm-dashboard`:
```sh
npm ci
npm run build -- --webpack
node scripts/shared-knowledge-preview.mjs
```
Open <http://127.0.0.1:3222/preview>. This creates a synthetic localhost demo session and opens `/ui/memory/demo/`. The preview serves the production export and read-only fixtures; it does not require a running proxy or database. The production dashboard continues to use its normal authentication and Memory permissions.
Step links use `?step=2`, `?step=3`, and `?step=4`. Switching steps keeps local demo state; reloading or selecting **Reset Demo** resets it. Jumping to a later step without saving a draft uses a clearly labeled published sample memo.
## Prototype boundaries
All sample data is synthetic. Saving, searching, judging, recording outcomes, and periodic review are simulated in browser state. Postgres persistence, vector/text indexes, service-side model review, real cross-user retrieval, and automatic scheduling are proposed behavior, not implemented services.
Historical counts and review thresholds are illustrative. Unknown outcomes are excluded from usefulness rates. Recorded outcomes retain the memo version used, and a promoted skill retains its source version.
## Message to accompany screenshots
> Hey, I put this into LiteLLM's Memory UI:
>
> 1. Choose the user/operator systems we want agents to remember.
> 2. An agent saves a researched finding as a shared memo.
> 3. A judge reviews corrections; other agents retrieve the published version and report outcomes.
> 4. Periodic review promotes useful patterns to skills, archives weak guidance, and keeps useful rare fixes.
>
> This is an interactive UI demo with simulated data. Is this the flow you had in mind?

Binary file not shown.

After

Width:  |  Height:  |  Size: 125 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 134 KiB

File diff suppressed because it is too large Load diff

View file

@ -38,6 +38,7 @@
"@tanstack/react-table": "8.21.3",
"@tanstack/react-virtual": "3.14.13",
"@types/papaparse": "5.5.2",
"antd": "5.29.3",
"class-variance-authority": "0.7.1",
"clsx": "^2.1.1",
"date-fns": "^4.4.0",

View file

@ -0,0 +1,272 @@
import { createHmac, randomBytes } from "node:crypto";
import { createReadStream } from "node:fs";
import { stat } from "node:fs/promises";
import { createServer, request as httpRequest } from "node:http";
import { dirname, extname, resolve, sep } from "node:path";
import { fileURLToPath } from "node:url";
const dashboardDir = resolve(dirname(fileURLToPath(import.meta.url)), "..");
const exportDir = resolve(dashboardDir, "out");
const publicDir = resolve(dashboardDir, "public");
const proxyDir = resolve(dashboardDir, "../../litellm/proxy");
const port = Number(process.env.DEMO_PORT ?? 3222);
const previewOrigin = `http://127.0.0.1:${port}`;
const nextOrigin = process.env.DEMO_NEXT_ORIGIN ? new URL(process.env.DEMO_NEXT_ORIGIN) : null;
const sessionKey = `demo-only-${randomBytes(24).toString("hex")}`;
const signingKey = randomBytes(32);
const user = { user_id: "demo-admin", user_email: "demo@example.invalid", user_role: "proxy_admin" };
const sessionExpires = Math.floor(Date.now() / 1000) + 12 * 60 * 60;
const jwtHeader = Buffer.from(JSON.stringify({ alg: "HS256", typ: "JWT" })).toString("base64url");
const session = {
...user,
key: sessionKey,
exp: sessionExpires,
premium_user: false,
login_method: "demo",
password_reset_required: false,
disabled_non_admin_personal_key_creation: false,
};
const jwtPayload = Buffer.from(JSON.stringify(session)).toString("base64url");
const jwtBody = `${jwtHeader}.${jwtPayload}`;
const sessionToken = `${jwtBody}.${createHmac("sha256", signingKey).update(jwtBody).digest("base64url")}`;
if (nextOrigin && (nextOrigin.protocol !== "http:" || !["127.0.0.1", "localhost"].includes(nextOrigin.hostname))) {
process.stderr.write("DEMO_NEXT_ORIGIN must be a local HTTP origin\n");
process.exit(1);
}
if (nextOrigin?.port === String(port)) {
process.stderr.write("Next and the preview server need different ports\n");
process.exit(1);
}
const fixtures = {
"/litellm/.well-known/litellm-ui-config": {
server_root_path: "",
proxy_base_url: previewOrigin,
auto_redirect_to_sso: false,
admin_ui_disabled: false,
sso_configured: false,
is_control_plane: false,
workers: [],
},
"/ui/litellm-runtime-config.json": { backend_url: previewOrigin },
"/litellm-runtime-config.json": { backend_url: previewOrigin },
"/get/ui_settings": { values: {} },
"/get/ui_theme_settings": { values: {} },
"/public/litellm_blog_posts": { posts: [] },
"/api/plugins": [],
"/management/v1/users/me": user,
"/health/readiness": { status: "healthy" },
"/health/readiness/details": { status: "healthy", litellm_version: "demo", log_level: "INFO" },
"/health/deployment_warnings": { ignore_available: false, warnings: [] },
"/health/license": {
has_license: false,
license_type: null,
expiration_date: null,
allowed_features: [],
limits: { max_users: null, max_teams: null },
},
"/user/available_users": {
total_users: null,
total_users_used: 0,
total_users_remaining: null,
total_teams: null,
total_teams_used: 0,
total_teams_remaining: null,
},
"/team/list": [],
"/organization/list": [],
"/v1/memory": { memories: [], total: 0 },
"/sso/get/ui_settings": { PROXY_BASE_URL: previewOrigin, PROXY_LOGOUT_URL: `${previewOrigin}/preview` },
"/get/user_banner": { enabled: false, message: "", severity: "info", revision: "demo" },
"/get/latest_release_info": {
version: "demo",
release_url: "",
new_features: 0,
bug_fixes: 0,
other_updates: 0,
},
"/telemetry/ui_events/enabled": { enabled: false },
"/telemetry/settings": {
available_destinations: [],
destination: null,
destination_set_by_environment: false,
editable: false,
environment_variables: [],
flush_interval_seconds: 300,
groups: [],
report: null,
report_is_sample: true,
retention_days: 0,
set_by_environment: false,
stored_destination: null,
stored_groups: [],
vetoed: false,
},
};
const publicFixtures = new Set([
"/litellm/.well-known/litellm-ui-config",
"/ui/litellm-runtime-config.json",
"/litellm-runtime-config.json",
"/get/ui_settings",
"/get/ui_theme_settings",
"/public/litellm_blog_posts",
"/health/readiness",
]);
const contentTypes = {
".html": "text/html; charset=utf-8",
".js": "text/javascript; charset=utf-8",
".css": "text/css; charset=utf-8",
".json": "application/json; charset=utf-8",
".txt": "text/plain; charset=utf-8",
".svg": "image/svg+xml",
".png": "image/png",
".ico": "image/x-icon",
".woff": "font/woff",
".woff2": "font/woff2",
".webp": "image/webp",
};
function json(response, status, value) {
response.writeHead(status, { "Content-Type": "application/json; charset=utf-8" });
response.end(JSON.stringify(value));
}
function isAuthorized(request) {
return request.headers.authorization === `Bearer ${sessionKey}` && Date.now() < sessionExpires * 1000;
}
function openPreview(response, search) {
const destination = nextOrigin ? "/memory/demo/" : "/ui/memory/demo/";
response.writeHead(302, {
Location: `${destination}${search}`,
"Set-Cookie": `token=${sessionToken}; Path=/; SameSite=Lax; Max-Age=43200`,
});
response.end();
}
async function serveFile(request, response, filename) {
const details = await stat(filename).catch(() => null);
if (!details?.isFile()) return false;
response.writeHead(200, {
"Content-Type": contentTypes[extname(filename)] ?? "application/octet-stream",
"Content-Length": details.size,
});
if (request.method === "HEAD") response.end();
else createReadStream(filename).pipe(response);
return true;
}
async function serveExport(request, response, pathname) {
const uiPath = pathname.replace(/^\/ui(?=\/|$)/, "").replace(/^\/litellm-asset-prefix(?=\/)/, "");
const relative = uiPath.replace(/^\/+/, "");
const exported = resolve(exportDir, relative);
const publicAsset = resolve(publicDir, relative);
const candidates = [exported, `${exported}.html`, resolve(exported, "index.html"), publicAsset];
for (const candidate of candidates) {
const insideExport = candidate.startsWith(`${exportDir}${sep}`);
const insidePublic = candidate.startsWith(`${publicDir}${sep}`);
if ((insideExport || insidePublic) && (await serveFile(request, response, candidate))) return;
}
json(response, 404, { error: "No exported page found. Build the dashboard or set DEMO_NEXT_ORIGIN." });
}
function proxyToNext(request, response, url) {
const target = new URL(url.pathname.replace(/^\/ui(?=\/|$)/, "") + url.search, nextOrigin);
const forwardedHeaders = Object.fromEntries(
Object.entries(request.headers).filter(
([name]) => !["authorization", "cookie", "host", "connection"].includes(name),
),
);
const headers = { ...forwardedHeaders, "x-shared-knowledge-preview-proxy": "1" };
const upstream = httpRequest(target, { method: request.method, headers }, (upstreamResponse) => {
response.writeHead(upstreamResponse.statusCode ?? 502, upstreamResponse.headers);
upstreamResponse.pipe(response);
});
upstream.on("error", () =>
json(response, 502, { error: "Next.js is not ready. Start the local dev server and reload." }),
);
request.pipe(upstream);
}
function isPageOrAsset(request, url) {
return (
!request.headers.accept?.includes("application/json") &&
/^\/(?:ui(?:\/|$)|memory(?:\/|$)|login(?:\/|$)|_next\/|__nextjs|litellm-asset-prefix\/|assets\/|favicon\.ico)/.test(
url.pathname,
)
);
}
async function handleRequest(request, response) {
response.setHeader("Cache-Control", "no-store");
response.setHeader("X-Content-Type-Options", "nosniff");
if (request.headers["x-shared-knowledge-preview-proxy"] === "1") {
json(response, 404, { error: "The requested route is missing from the local Next.js server." });
return;
}
const url = new URL(request.url ?? "/", previewOrigin);
const hostname = (request.headers.host ?? "").split(":")[0];
if (!["127.0.0.1", "localhost"].includes(hostname)) {
json(response, 403, { error: "This preview is local only." });
return;
}
if (request.headers.origin) {
const allowedOrigins = [previewOrigin, `http://localhost:${port}`, nextOrigin?.origin];
if (!allowedOrigins.includes(request.headers.origin)) {
json(response, 403, { error: "Only the local demo can use preview fixtures." });
return;
}
response.setHeader("Access-Control-Allow-Origin", request.headers.origin);
response.setHeader("Access-Control-Allow-Headers", "Authorization, Content-Type, Accept");
response.setHeader("Access-Control-Allow-Methods", "GET, HEAD, OPTIONS");
}
if (request.method === "OPTIONS") {
response.writeHead(204);
response.end();
return;
}
if (!["GET", "HEAD"].includes(request.method ?? "")) {
json(response, 405, { error: "This preview serves read-only fixtures. Demo actions stay in the browser." });
return;
}
if (["/", "/preview", "/preview/", "/knowledge-demo", "/knowledge-demo/"].includes(url.pathname)) {
openPreview(response, url.search);
return;
}
if (Object.hasOwn(fixtures, url.pathname)) {
const permitted = publicFixtures.has(url.pathname) || isAuthorized(request);
json(
response,
permitted ? 200 : 401,
permitted ? fixtures[url.pathname] : { error: "Open /preview to start a demo session." },
);
return;
}
if (url.pathname === "/get_image") {
await serveFile(request, response, resolve(proxyDir, "logo.png"));
return;
}
if (url.pathname === "/get_favicon") {
await serveFile(request, response, resolve(dashboardDir, "src/app/favicon.ico"));
return;
}
if (!isPageOrAsset(request, url)) {
json(response, 404, {
error: "No fixture exists for this endpoint. The preview never contacts a production service.",
});
return;
}
if (nextOrigin) proxyToNext(request, response, url);
else await serveExport(request, response, decodeURIComponent(url.pathname));
}
const server = createServer((request, response) => {
void handleRequest(request, response).catch(() => {
if (!response.headersSent) json(response, 500, { error: "The local preview could not serve this request." });
else response.end();
});
});
server.listen(port, "127.0.0.1", () => {
process.stdout.write(`Local fixture preview ready at ${previewOrigin}/preview\n`);
});

View file

@ -6,6 +6,7 @@ import React from "react";
import { beforeEach, describe, expect, it, vi } from "vitest";
import { MemoryRow } from "@/components/networking";
import { uiHref } from "@/utils/uiHref";
import { MemoryView } from "./MemoryView";
@ -88,6 +89,12 @@ describe("MemoryView", () => {
expect(screen.getByText(/Scoped to memories visible to your user \/ team \(admins see all\)/)).toBeInTheDocument();
});
it("should link to the shared knowledge demo from Memory", () => {
renderView(null);
expect(screen.getByRole("link", { name: "Shared knowledge demo" })).toHaveAttribute("href", uiHref("memory/demo"));
});
it("opens the create modal from the New memory button", async () => {
const user = userEvent.setup();
renderView(null);

View file

@ -4,6 +4,7 @@ import { useDebouncedValue } from "@tanstack/react-pacer/debouncer";
import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
import type { PaginationState } from "@tanstack/react-table";
import { Plus } from "lucide-react";
import { Button as DemoButton } from "antd";
import React, { useCallback, useMemo, useState } from "react";
import { MemoryRow, createMemory, deleteMemory, fetchMemoryList, updateMemory } from "@/components/networking";
@ -11,6 +12,7 @@ import DeleteResourceModal from "@/components/common_components/DeleteResourceMo
import { toast } from "@/lib/toast";
import { Button } from "@/components/ui/button";
import { DEBOUNCE_WAIT_MS } from "@/utils/debounceConstants";
import { uiHref } from "@/utils/uiHref";
import { MemoryDetailDrawer } from "./MemoryDetailDrawer";
import { MemoryEditModal } from "./MemoryEditModal";
@ -176,7 +178,7 @@ export const MemoryView: React.FC<MemoryViewProps> = ({ accessToken }) => {
return (
<div className="w-full p-6">
<div className="flex flex-col gap-6">
<div className="flex items-start justify-between gap-4">
<div className="flex flex-col items-start justify-between gap-4 md:flex-row">
<div>
<h1 className="text-2xl font-semibold text-foreground">Memory</h1>
<p className="mt-1 text-sm text-muted-foreground">
@ -187,10 +189,13 @@ export const MemoryView: React.FC<MemoryViewProps> = ({ accessToken }) => {
. Scoped to memories visible to your user / team (admins see all).
</p>
</div>
<Button onClick={() => setIsCreateOpen(true)}>
<Plus />
New memory
</Button>
<div className="flex flex-wrap items-center gap-2">
<DemoButton href={uiHref("memory/demo")}>Shared knowledge demo</DemoButton>
<Button onClick={() => setIsCreateOpen(true)}>
<Plus />
New memory
</Button>
</div>
</div>
<MemoryTable

View file

@ -0,0 +1,151 @@
import { act, fireEvent, screen, waitFor, within } from "@testing-library/react";
import userEvent from "@testing-library/user-event";
import type { OnUrlUpdateFunction } from "nuqs/adapters/testing";
import { describe, expect, it, vi } from "vitest";
import { uiHref } from "@/utils/uiHref";
import { renderWithProviders } from "../../../../../tests/test-utils";
import SharedKnowledgeDemo from "./SharedKnowledgeDemo";
const initialTitle = "Exclude inactive accounts from cross-account totals";
const sampleNotice = "Using a published sample memo. Save your draft in step 2 to use it here.";
async function chooseStep(user: ReturnType<typeof userEvent.setup>, name: RegExp) {
const step = within(screen.getByRole("navigation", { name: "Demo steps" })).getByRole("button", { name });
await user.click(step);
await waitFor(() => expect(step).toHaveAttribute("aria-current", "step"));
}
describe("SharedKnowledgeDemo", () => {
it("should render the knowledge categories with a link back to Memory", () => {
renderWithProviders(<SharedKnowledgeDemo />);
expect(screen.getByRole("heading", { name: "Shared knowledge", exact: true })).toBeInTheDocument();
expect(screen.getByRole("link", { name: "Back to Memory" })).toHaveAttribute("href", uiHref("memory"));
expect(screen.getByRole("switch", { name: "Enable Account reporting" })).toBeChecked();
expect(screen.getByText("User systems", { exact: true })).toBeInTheDocument();
expect(screen.getByText("Operator systems", { exact: true })).toBeInTheDocument();
});
it("should carry a scoped memo through publication, reuse, feedback, and skill promotion", async () => {
const user = userEvent.setup();
const onUrlUpdate = vi.fn<OnUrlUpdateFunction>();
const title = "Use active child accounts in reporting totals";
renderWithProviders(<SharedKnowledgeDemo />, { searchParams: "?workspace=demo", onUrlUpdate });
await user.click(screen.getByRole("switch", { name: "Enable Account reporting" }));
await chooseStep(user, /Capture a memo/);
expect(screen.getByRole("button", { name: "Save Memo to Shared Knowledge" })).toBeDisabled();
expect(screen.getByRole("alert")).toHaveTextContent("Enable Account reporting in step 1 to save this memo.");
await chooseStep(user, /Define scope/);
await user.click(screen.getByRole("switch", { name: "Enable Account reporting" }));
await chooseStep(user, /Capture a memo/);
act(() => {
fireEvent.change(screen.getByRole("textbox", { name: "Title", exact: true }), { target: { value: title } });
fireEvent.change(screen.getByRole("textbox", { name: "Summary", exact: true }), {
target: { value: "Filter active parent and child accounts before calculating the total." },
});
});
await user.click(screen.getByRole("button", { name: "Save Memo to Shared Knowledge" }));
expect(screen.getByRole("heading", { name: "Published memo", exact: true })).toBeInTheDocument();
await chooseStep(user, /Review & reuse/);
expect(screen.getByRole("heading", { name: title, exact: true })).toBeInTheDocument();
expect(screen.queryByText(sampleNotice)).not.toBeInTheDocument();
await user.click(screen.getByRole("button", { name: "Run Judge Review" }));
expect(screen.getByText("Accepted · v2 published", { exact: true })).toBeInTheDocument();
expect(screen.getByRole("button", { name: "Evidence-backed Update" })).toBeDisabled();
await user.click(screen.getByRole("button", { name: "Load v2 into Session" }));
await user.click(screen.getByRole("button", { name: "Record Helpful Outcome" }));
expect(screen.getByRole("button", { name: "Outcome Recorded" })).toBeDisabled();
await chooseStep(user, /Learn & curate/);
const memoRow = screen.getByRole("row", { name: new RegExp(title) });
expect(memoRow).toHaveTextContent("29 helpful / 31 known");
expect(memoRow).toHaveTextContent("33 loads · 8 agents");
await user.click(screen.getByRole("button", { name: "Run Periodic Review" }));
expect(memoRow).toHaveTextContent("Promoted to skill");
expect(screen.getByRole("row", { name: /Legacy account-total workaround/ })).toHaveTextContent("Archived");
expect(screen.getByRole("row", { name: /Bazel: recover from a corrupted JAR/ })).toHaveTextContent("Retained");
await user.click(screen.getByRole("button", { name: "View Skill" }));
expect(screen.getByRole("dialog", { name: "Account reporting checks" })).toHaveTextContent(
"Derived from memo_014 · v2",
);
await user.click(screen.getByRole("button", { name: "Close Skill" }));
await waitFor(() => expect(onUrlUpdate.mock.calls.at(-1)?.[0].searchParams.get("step")).toBe("4"));
expect(onUrlUpdate.mock.calls.at(-1)?.[0].searchParams.get("workspace")).toBe("demo");
expect(onUrlUpdate.mock.calls.at(-1)?.[0].options.history).toBe("push");
});
it("should preserve a published version and recorded feedback when a later correction is rejected", async () => {
const user = userEvent.setup();
renderWithProviders(<SharedKnowledgeDemo />, { searchParams: "?step=3" });
await user.click(screen.getByRole("button", { name: "Run Judge Review" }));
await user.click(screen.getByRole("button", { name: "Load v2 into Session" }));
await user.click(screen.getByRole("button", { name: "Record Helpful Outcome" }));
act(() => {
fireEvent.change(screen.getByRole("textbox", { name: "Search shared knowledge" }), {
target: { value: "unrelated quantum penguins" },
});
});
await user.click(screen.getByRole("button", { name: "Search", exact: true }));
expect(screen.getByText("No matching demo memos", { exact: true })).toBeInTheDocument();
act(() => {
fireEvent.change(screen.getByRole("textbox", { name: "Search shared knowledge" }), {
target: { value: "inactive accounts" },
});
});
await user.click(screen.getByRole("button", { name: "Search", exact: true }));
await user.click(screen.getByRole("button", { name: "Try Unsupported Update" }));
await user.click(screen.getByRole("button", { name: "Run Judge Review" }));
expect(screen.getByText("Rejected · v2 remains published", { exact: true })).toBeInTheDocument();
expect(screen.getByRole("button", { name: "Load v2 into Session" })).toBeEnabled();
expect(screen.getByRole("button", { name: "Evidence-backed Update" })).toBeDisabled();
await chooseStep(user, /Learn & curate/);
expect(screen.getByRole("row", { name: new RegExp(initialTitle) })).toHaveTextContent("29 helpful / 31 known");
});
it("should keep an unsaved draft separate and preserve the version used to promote a skill", async () => {
const user = userEvent.setup();
const draftTitle = "Unpublished reporting investigation";
renderWithProviders(<SharedKnowledgeDemo />, { searchParams: "?step=2" });
act(() => {
fireEvent.change(screen.getByRole("textbox", { name: "Title", exact: true }), { target: { value: draftTitle } });
});
await chooseStep(user, /Review & reuse/);
expect(screen.getByText(sampleNotice)).toBeInTheDocument();
expect(screen.queryByText(draftTitle)).not.toBeInTheDocument();
expect(screen.getByRole("heading", { name: initialTitle, exact: true })).toBeInTheDocument();
await chooseStep(user, /Learn & curate/);
await user.click(screen.getByRole("button", { name: "Run Periodic Review" }));
await chooseStep(user, /Review & reuse/);
await user.click(screen.getByRole("button", { name: "Run Judge Review" }));
await chooseStep(user, /Learn & curate/);
await user.click(screen.getByRole("button", { name: "View Skill" }));
expect(screen.getByRole("dialog", { name: "Account reporting checks" })).toHaveTextContent(
"Derived from memo_014 · v1",
);
expect(screen.getByRole("dialog", { name: "Account reporting checks" })).toHaveTextContent(
"Explicitly exclude inactive accounts from the total.",
);
await user.click(screen.getByRole("button", { name: "Close Skill" }));
await chooseStep(user, /Capture a memo/);
await user.click(screen.getByRole("button", { name: "Save Memo to Shared Knowledge" }));
await chooseStep(user, /Review & reuse/);
expect(screen.getByRole("heading", { name: draftTitle, exact: true })).toBeInTheDocument();
expect(screen.getByRole("button", { name: "Load v1 into Session" })).toBeEnabled();
});
it.each([
["2", "Turn a hard-won finding into a memo"],
["3", "Review corrections. Share the better answer."],
["4", "Let outcomes improve the knowledge base"],
["99", "Define what agents should remember"],
])("should open the valid step or fall back to scope for step=%s", (step, heading) => {
renderWithProviders(<SharedKnowledgeDemo />, { searchParams: `?step=${step}` });
expect(screen.getByRole("heading", { name: heading, exact: true })).toBeInTheDocument();
});
});

View file

@ -0,0 +1,709 @@
"use client";
import { useState, useSyncExternalStore, type FormEvent } from "react";
import { Button, ConfigProvider, Input, Modal, Switch, Tag, theme } from "antd";
import { useTheme } from "next-themes";
import { parseAsStringLiteral, useQueryState } from "nuqs";
import { uiHref } from "@/utils/uiHref";
import { Eyebrow, Note, Panel } from "./SharedKnowledgePrimitives";
import { SharedKnowledgeReview } from "./SharedKnowledgeReview";
import {
ArrowRight,
BookOpen,
Bot,
Check,
CheckCheck,
Clock3,
Database,
FileText,
Layers3,
ListFilter,
LockKeyhole,
Sparkles,
Terminal,
Users,
} from "lucide-react";
const steps = ["Define scope", "Capture a memo", "Review & reuse", "Learn & curate"];
const titles = [
"Define what agents should remember",
"Turn a hard-won finding into a memo",
"Review corrections. Share the better answer.",
"Let outcomes improve the knowledge base",
];
const subtitles = [
"Organize shared knowledge by system and by the people who use it.",
"An agent resolves an unusual problem and saves the lesson for the next person.",
"Agents propose changes; a service-side LLM judge checks them before publication.",
"A periodic review promotes proven patterns and archives low-value knowledge.",
];
const initialTitle = "Exclude inactive accounts from cross-account totals";
const initialSummary =
"The reporting service includes inactive accounts by default. Explicitly exclude them when calculating totals.";
const categories = [
{
name: "Account reporting",
audience: "User",
count: 18,
description: "Totals, account lifecycle, and reporting quirks",
icon: Users,
},
{
name: "Billing",
audience: "User",
count: 12,
description: "Invoices, credits, and reconciliation",
icon: FileText,
},
{
name: "Bazel & builds",
audience: "Operator",
count: 9,
description: "Build failures, caches, and dependency recovery",
icon: Terminal,
},
{
name: "Deployments",
audience: "Operator",
count: 7,
description: "Rollouts, service health, and incident recovery",
icon: Layers3,
},
];
const stepValues = ["1", "2", "3", "4"] as const;
const stepParser = parseAsStringLiteral(stepValues).withDefault("1").withOptions({ history: "push" });
function subscribeHydration() {
return () => {};
}
export default function SharedKnowledgeDemo() {
const [stepValue, setStepValue] = useQueryState("step", stepParser);
const step = Number(stepValue);
const { resolvedTheme } = useTheme();
const hydrated = useSyncExternalStore(
subscribeHydration,
() => true,
() => false,
);
const dark = hydrated && resolvedTheme === "dark";
const [enabled, setEnabled] = useState(categories.map(() => true));
const [selected, setSelected] = useState(0);
const [memoTitle, setMemoTitle] = useState(initialTitle);
const [summary, setSummary] = useState(initialSummary);
const [saved, setSaved] = useState(false);
const [version, setVersion] = useState(1);
const [proposalBaseVersion, setProposalBaseVersion] = useState(1);
const [judge, setJudge] = useState<"pending" | "accepted" | "rejected">("pending");
const [proposal, setProposal] = useState<"supported" | "unsupported">("supported");
const [loads, setLoads] = useState<{ version: number; helpful: boolean }[]>([]);
const [activeLoad, setActiveLoad] = useState<number | null>(null);
const [query, setQuery] = useState("cross-account totals include inactive accounts");
const [search, setSearch] = useState("cross-account totals include inactive accounts");
const [skillVersion, setSkillVersion] = useState<number | null>(null);
const reviewed = skillVersion !== null;
const loaded = activeLoad !== null;
const outcome = activeLoad !== null && loads[activeLoad]?.helpful;
const loadedVersion = activeLoad !== null ? loads[activeLoad]?.version : version;
const helpfulCount = loads.filter((load) => load.helpful).length;
const publishedTitle = saved ? memoTitle : initialTitle;
const [skillOpen, setSkillOpen] = useState(false);
const [evidenceOpen, setEvidenceOpen] = useState(false);
const hasMatch = /account|total|report|inactive|sum/i.test(search);
const enabledCount = enabled.filter(Boolean).length;
const category = categories[selected];
const canSave = enabled[0] && memoTitle.trim().length > 0 && summary.trim().length > 0;
const go = (next: number) => {
void setStepValue(stepValues[next - 1]);
};
const chooseProposal = (next: "supported" | "unsupported") => {
if (next === "supported" && version >= 2) return;
setProposal(next);
setProposalBaseVersion(version);
setJudge("pending");
setActiveLoad(null);
};
const saveMemo = () => {
setSaved(true);
setVersion(1);
setProposalBaseVersion(1);
setJudge("pending");
setProposal("supported");
setLoads([]);
setActiveLoad(null);
setSkillVersion(null);
};
const reviewProposal = () => {
setJudge(proposal === "supported" ? "accepted" : "rejected");
if (proposal === "supported") setVersion((current) => current + 1);
setActiveLoad(null);
};
const searchMemos = (event: FormEvent<HTMLFormElement>) => {
event.preventDefault();
setSearch(query);
setActiveLoad(null);
};
const loadMemo = () => {
setActiveLoad(loads.length);
setLoads((previous) => [...previous, { version, helpful: false }]);
};
const recordHelpfulOutcome = () => {
setLoads((previous) => previous.map((load, index) => (index === activeLoad ? { ...load, helpful: true } : load)));
};
const reset = () => {
setEnabled(categories.map(() => true));
setSelected(0);
setMemoTitle(initialTitle);
setSummary(initialSummary);
setSaved(false);
setVersion(1);
setProposalBaseVersion(1);
setJudge("pending");
setProposal("supported");
setActiveLoad(null);
setSkillVersion(null);
setLoads([]);
setQuery("cross-account totals include inactive accounts");
setSearch("cross-account totals include inactive accounts");
go(1);
};
return (
<ConfigProvider
theme={{
algorithm: dark ? theme.darkAlgorithm : theme.defaultAlgorithm,
token: {
fontFamily: "inherit",
borderRadius: 8,
fontSize: 13,
colorPrimary: dark ? "#ededed" : "#171717",
},
components: { Button: { primaryColor: dark ? "#0a0a0a" : "#ffffff" } },
}}
>
<section
aria-label="Shared knowledge demo"
className="mx-auto flex w-full max-w-6xl flex-col gap-6 px-6 py-6 text-foreground"
>
<div className="flex items-center justify-between gap-4">
<div>
<h1 className="text-2xl font-semibold tracking-tight">Shared knowledge</h1>
<p className="mt-1 text-xs text-muted-foreground">Lessons from one agent. Useful to every agent.</p>
</div>
<div className="flex flex-wrap items-center gap-2 text-xs text-muted-foreground">
<Tag color="blue">Interactive demo</Tag>
<Button href={uiHref("memory")}>Back to Memory</Button>
<span className="hidden items-center gap-1.5 sm:inline-flex">
<LockKeyhole className="size-3.5" />
Workspace shared
</span>
</div>
</div>
<nav
aria-label="Demo steps"
className="grid grid-cols-2 gap-2 rounded-xl border border-border bg-card p-2 sm:grid-cols-4"
>
{steps.map((label, index) => (
<button
key={label}
onClick={() => go(index + 1)}
aria-current={step === index + 1 ? "step" : undefined}
className={`flex items-center gap-2.5 rounded-lg px-3 py-2.5 text-left text-xs transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring/50 ${step === index + 1 ? "bg-accent font-medium text-foreground" : "text-muted-foreground hover:bg-muted"}`}
>
<span
className={`grid size-6 shrink-0 place-items-center rounded-full border text-[11px] ${step === index + 1 ? "border-foreground bg-foreground text-background" : "border-border"}`}
>
{index + 1}
</span>
{label}
</button>
))}
</nav>
<div className="flex items-start gap-4">
<span className="grid size-11 shrink-0 place-items-center rounded-xl border border-border bg-muted font-mono text-xl">
{step}
</span>
<div>
<h2 className="text-xl font-semibold tracking-tight">{titles[step - 1]}</h2>
<p className="mt-1.5 text-sm text-muted-foreground">{subtitles[step - 1]}</p>
</div>
</div>
{step >= 3 && !saved && (
<p className="text-xs text-muted-foreground">
Using a published sample memo. Save your draft in step 2 to use it here.
</p>
)}
{step === 1 && (
<>
<div className="grid gap-4 lg:grid-cols-[1.35fr_1fr]">
<Panel
title={
<>
<ListFilter className="size-4 text-muted-foreground" />
Knowledge categories
</>
}
extra={<Tag>{enabledCount} enabled</Tag>}
>
<div className="p-2">
{["User", "Operator"].map((audience) => (
<div key={audience} className="p-2">
<Eyebrow>{audience} systems</Eyebrow>
{categories.map(
(item, i) =>
item.audience === audience && (
<div
key={item.name}
className={`mb-2 flex items-center gap-3 rounded-lg border p-3 ${selected === i ? "border-foreground/30 bg-accent/60" : "border-border"}`}
>
<button
onClick={() => setSelected(i)}
className="flex min-w-0 flex-1 items-center gap-3 rounded text-left focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring/50"
aria-pressed={selected === i}
>
<item.icon className="size-4 shrink-0 text-muted-foreground" />
<span className="min-w-0">
<span className="block text-sm font-medium">{item.name}</span>
<span className="mt-0.5 block text-xs text-muted-foreground">{item.count} memos</span>
</span>
</button>
<Switch
size="small"
aria-label={`Enable ${item.name}`}
checked={enabled[i]}
onChange={(value) =>
setEnabled((previous) =>
previous.map((entry, index) => (index === i ? value : entry)),
)
}
/>
</div>
),
)}
</div>
))}
</div>
</Panel>
<Panel title="Category settings" extra={<Tag>{category.audience}</Tag>}>
<div className="space-y-5 p-4">
<div>
<Eyebrow>Selected category</Eyebrow>
<h3 className="text-base font-semibold tracking-tight">{category.name}</h3>
<p className="mt-2 text-xs leading-relaxed text-muted-foreground">{category.description}</p>
</div>
<div className="border-t border-border pt-4">
<Eyebrow>When should an agent write a memo?</Eyebrow>
<ul className="space-y-3 text-sm">
<li className="flex gap-2">
<Check className="mt-0.5 size-4 shrink-0 text-muted-foreground" />
An unexpected behavior took research to resolve
</li>
<li className="flex gap-2">
<Check className="mt-0.5 size-4 shrink-0 text-muted-foreground" />
The lesson will help someone else
</li>
<li className="flex gap-2">
<Check className="mt-0.5 size-4 shrink-0 text-muted-foreground" />A source session supports the
finding
</li>
</ul>
</div>
<Note icon={<Users className="size-4" />}>
<strong className="block text-foreground">Shared within this workspace</strong>
<span className="mt-1 block">
User and operator are knowledge categories. Access permissions still determine who can retrieve
each memo.
</span>
</Note>
</div>
</Panel>
</div>
<Note icon={<Database className="size-4" />}>
<strong className="text-foreground">One searchable memo library</strong>
<span className="mx-2">·</span>Postgres stores the memo content, versions, and evidence. Vector + text
indexes make it discoverable across agents.
</Note>
</>
)}
{step === 2 && (
<div className="grid items-stretch gap-4 lg:grid-cols-[1fr_1.08fr]">
<Panel
title={
<>
<Bot className="size-4 text-muted-foreground" />
Reporting agent
</>
}
extra={<Tag>Session 8f2a</Tag>}
>
<div className="space-y-5 p-4">
<div className="rounded-lg bg-muted p-3">
<Eyebrow>Alex · Finance</Eyebrow>
<p className="text-sm leading-relaxed">
Why is the cross-account total higher than the sum of our active accounts?
</p>
</div>
<div className="flex gap-3">
<span className="mt-0.5 grid size-7 shrink-0 place-items-center rounded-lg border border-border">
<Bot className="size-4" />
</span>
<div className="space-y-3 text-sm leading-relaxed">
<p>I compared the account lifecycle rules with the reporting queries.</p>
<div className="space-y-2 border-l border-border pl-3 text-xs text-muted-foreground">
<p className="flex items-center gap-2">
<Check className="size-3" />
Read reporting service documentation
</p>
<p className="flex items-center gap-2">
<Check className="size-3" />
Traced the aggregation query
</p>
<p className="flex items-center gap-2">
<Check className="size-3" />
Verified with and without inactive accounts
</p>
</div>
<p>The service includes inactive accounts by default. Filtering them out reconciled the total.</p>
</div>
</div>
<div className="rounded-lg border border-border p-3">
<div className="mb-2 flex items-center justify-between">
<span className="flex items-center gap-2 font-mono text-xs">
<BookOpen className="size-3.5" />
save_memo
</span>
<Tag>{saved ? "Saved" : "Proposed"}</Tag>
</div>
<p className="text-xs leading-relaxed text-muted-foreground">
This took 14 minutes of investigation. I’ll record the behavior and the fix so other agents can
reuse it.
</p>
</div>
<Button block onClick={() => setEvidenceOpen(true)} icon={<FileText className="size-3.5" />}>
View Source Evidence
</Button>
</div>
</Panel>
<Panel
title={
<>
<FileText className="size-4 text-muted-foreground" />
{saved ? "Published memo" : "New memo"}
</>
}
extra={saved ? <Tag color="green">v1 · Published</Tag> : <Tag>Draft</Tag>}
>
<div className="space-y-4 p-4">
<div className="flex flex-wrap gap-1">
<Tag>Account reporting</Tag>
<Tag>User systems</Tag>
</div>
<div>
<label htmlFor="memo-title" className="mb-1.5 block text-xs font-medium">
Title
</label>
<Input.TextArea
id="memo-title"
rows={2}
value={memoTitle}
disabled={saved}
onChange={(e) => setMemoTitle(e.target.value)}
/>
</div>
<div>
<label htmlFor="memo-summary" className="mb-1.5 block text-xs font-medium">
Summary
</label>
<Input.TextArea
id="memo-summary"
rows={3}
value={summary}
disabled={saved}
onChange={(e) => setSummary(e.target.value)}
/>
</div>
<div>
<Eyebrow>Guidance</Eyebrow>
<p className="text-sm leading-relaxed">
Explicitly filter to active accounts when calculating a cross-account total. Compare the result with
the active-account report.
</p>
</div>
<div className="flex items-center justify-between border-t border-border pt-3 text-xs text-muted-foreground">
<span>Source: session 8f2a</span>
<span>Author: Reporting agent</span>
</div>
{!enabled[0] && (
<p role="alert" className="text-xs text-destructive">
Enable Account reporting in step 1 to save this memo.
</p>
)}
<Button
type="primary"
block
disabled={!canSave || saved}
onClick={saveMemo}
icon={saved ? <CheckCheck className="size-4" /> : <BookOpen className="size-4" />}
>
{saved ? "Memo Saved · Available to Other Agents" : "Save Memo to Shared Knowledge"}
</Button>
<p className="text-[11px] text-muted-foreground">Demo action · stored in this page only</p>
</div>
</Panel>
</div>
)}
{step === 3 && (
<SharedKnowledgeReview
publishedTitle={publishedTitle}
version={version}
proposalBaseVersion={proposalBaseVersion}
proposal={proposal}
judge={judge}
chooseProposal={chooseProposal}
onReview={reviewProposal}
onOpenEvidence={() => setEvidenceOpen(true)}
query={query}
onQueryChange={setQuery}
onSearch={searchMemos}
hasMatch={hasMatch}
loaded={loaded}
outcome={outcome}
loadedVersion={loadedVersion}
onLoad={loadMemo}
onHelpfulOutcome={recordHelpfulOutcome}
/>
)}
{step === 4 && (
<>
<div className="grid grid-cols-2 gap-3 sm:grid-cols-4">
{[
{
label: "Memo loads",
value: 32 + loads.length,
detail: "Across 8 agents",
},
{
label: "Helpful",
value: 28 + helpfulCount,
detail: "Task resolved after use",
},
{
label: "Unhelpful",
value: 2,
detail: "Did not resolve the task",
},
{
label: "Unknown",
value: 2 + loads.length - helpfulCount,
detail: "No outcome reported",
},
].map((stat) => (
<div key={stat.label} className="rounded-xl border border-border bg-card p-4">
<p className="text-xs text-muted-foreground">{stat.label}</p>
<p className="my-2 text-3xl font-semibold tracking-tight">{stat.value}</p>
<p className="text-[11px] text-muted-foreground">{stat.detail}</p>
</div>
))}
</div>
<Panel
title={
<>
<Clock3 className="size-4 text-muted-foreground" />
Weekly knowledge review
</>
}
extra={<Tag>{reviewed ? "Review complete" : "Ready to run"}</Tag>}
>
<div className="flex flex-wrap items-center justify-between gap-3 border-b border-border px-4 py-3">
<p className="text-xs text-muted-foreground">
Last 30 days · outcomes are attached to the memo version used
</p>
<Button
type="primary"
disabled={reviewed}
onClick={() => setSkillVersion(version)}
icon={<Sparkles className="size-3.5" />}
>
{reviewed ? "Review Applied" : "Run Periodic Review"}
</Button>
</div>
<div className="overflow-x-auto">
<table className="w-full text-left text-xs">
<thead className="bg-muted/40 text-[10px] uppercase tracking-wider text-muted-foreground">
<tr>
<th className="px-4 py-3 font-medium">Memo</th>
<th className="px-3 py-3 font-medium">Usefulness</th>
<th className="px-4 py-3 font-medium">{reviewed ? "Decision" : "Recommendation"}</th>
</tr>
</thead>
<tbody className="divide-y divide-border">
<tr>
<td className="max-w-72 px-4 py-4">
<p className="text-sm font-medium">{publishedTitle}</p>
<p className="mt-1 text-xs text-muted-foreground">Account reporting · User</p>
</td>
<td className="whitespace-nowrap px-3 py-4">
<p>
{28 + helpfulCount} helpful / {30 + helpfulCount} known
</p>
<p className="mt-1 text-muted-foreground">{32 + loads.length} loads · 8 agents</p>
</td>
<td className="px-4 py-4">
<Tag color="green">{reviewed ? "Promoted to skill" : "Promote to skill"}</Tag>
<p className="mt-1 text-[11px] text-muted-foreground">Frequent + consistently useful</p>
</td>
</tr>
<tr>
<td className="px-4 py-4">
<p className="text-sm font-medium">Legacy account-total workaround</p>
<p className="mt-1 text-xs text-muted-foreground">Account reporting · User</p>
</td>
<td className="px-3 py-4">
<p>1 helpful / 10 known</p>
<p className="mt-1 text-muted-foreground">Superseded by current guidance</p>
</td>
<td className="px-4 py-4">
<Tag>{reviewed ? "Archived" : "Archive"}</Tag>
<p className="mt-1 text-[11px] text-muted-foreground">Removed from retrieval; history kept</p>
</td>
</tr>
<tr>
<td className="px-4 py-4">
<p className="text-sm font-medium">Bazel: recover from a corrupted JAR</p>
<p className="mt-1 text-xs text-muted-foreground">Bazel & builds · Operator</p>
</td>
<td className="px-3 py-4">
<p>2 helpful / 2 known</p>
<p className="mt-1 text-muted-foreground">Rare failure · last used 8 months ago</p>
</td>
<td className="px-4 py-4">
<Tag color="blue">{reviewed ? "Retained" : "Keep"}</Tag>
<p className="mt-1 text-[11px] text-muted-foreground">Rare does not mean low value</p>
</td>
</tr>
</tbody>
</table>
</div>
</Panel>
<div className="grid gap-4 lg:grid-cols-[1.1fr_1fr]">
<Panel
title={
<>
<Sparkles className="size-4 text-muted-foreground" />
{reviewed ? "Added to Skills" : "Skill preview"}
</>
}
extra={<Tag>{reviewed ? "Available" : "Candidate"}</Tag>}
>
<div className="space-y-3 p-4">
<h3 className="text-base font-semibold tracking-tight">Account reporting checks</h3>
<p className="text-xs leading-relaxed text-muted-foreground">
A reusable procedure: select active accounts, filter before aggregation, and reconcile the final
total.
</p>
<div className="flex flex-wrap items-center justify-between gap-2">
<span className="font-mono text-[11px] text-muted-foreground">
Source: memo_014 · v{skillVersion ?? version}
</span>
<Button size="small" onClick={() => setSkillOpen(true)}>
View Skill
</Button>
</div>
</div>
</Panel>
<Panel title="Review policy">
<div className="space-y-3 p-4 text-xs leading-relaxed text-muted-foreground">
<p>
<strong className="text-foreground">Promote</strong> after 20+ loads and at least 90% helpful
outcomes among 10+ known outcomes.
</p>
<p>
<strong className="text-foreground">Archive</strong> superseded guidance with less than 20% helpful
outcomes across 10+ known outcomes.
</p>
<p>
<strong className="text-foreground">Retain</strong> useful rare fixes. Unknown outcomes do not count
as failures.
</p>
</div>
</Panel>
</div>
</>
)}
<footer className="flex flex-wrap items-center justify-between gap-3 border-t border-border pt-4">
<div className="text-[11px] text-muted-foreground">Demo data · actions are simulated · resets on reload</div>
<div className="flex items-center gap-2">
<Button size="small" type="text" onClick={reset}>
Reset Demo
</Button>
{step > 1 && <Button onClick={() => go(step - 1)}>Back</Button>}
{step < 4 && (
<Button
type="primary"
onClick={() => go(step + 1)}
icon={<ArrowRight className="size-3.5" />}
iconPosition="end"
>
{steps[step]}
</Button>
)}
</div>
</footer>
</section>
<Modal
title="Source evidence · demo session"
open={evidenceOpen}
onCancel={() => setEvidenceOpen(false)}
footer={<Button onClick={() => setEvidenceOpen(false)}>Close Evidence</Button>}
>
<div className="space-y-4 py-3 text-sm">
<p>The agent checked the same reporting period with three query variants:</p>
<ol className="list-decimal space-y-2 pl-5">
<li>Unfiltered total: 1,280 account units.</li>
<li>Parent-only active filter: 1,120 account units.</li>
<li>
Active parent and child accounts filtered before aggregation: 1,000 account units, matching the
active-account report.
</li>
</ol>
<p className="text-xs text-muted-foreground">
Synthetic evidence for the prototype. No customer data is loaded.
</p>
</div>
</Modal>
<Modal
title="Account reporting checks"
open={skillOpen}
onCancel={() => setSkillOpen(false)}
footer={<Button onClick={() => setSkillOpen(false)}>Close Skill</Button>}
>
<div className="space-y-4 py-3 text-sm">
<Tag>{reviewed ? "Promoted in demo" : "Preview"}</Tag>
<p>Use when calculating or debugging totals across accounts.</p>
<ol className="list-decimal space-y-2 pl-5">
<li>Identify active accounts for the reporting period.</li>
<li>
{(skillVersion ?? version) >= 2
? "Exclude inactive parent and child accounts before aggregation."
: "Explicitly exclude inactive accounts from the total."}
</li>
<li>Reconcile against the active-account report.</li>
<li>Record whether the procedure resolved the discrepancy.</li>
</ol>
<p className="text-xs text-muted-foreground">
Derived from memo_014 · v{skillVersion ?? version}. Source evidence and version history are preserved.
</p>
</div>
</Modal>
</ConfigProvider>
);
}

View file

@ -0,0 +1,46 @@
import type { ReactNode } from "react";
import { Check } from "lucide-react";
export function Panel({
title,
extra,
children,
className = "",
}: {
title: ReactNode;
extra?: ReactNode;
children: ReactNode;
className?: string;
}) {
return (
<section className={`overflow-hidden rounded-xl border border-border bg-card ${className}`}>
<div className="flex min-h-12 items-center justify-between gap-2 border-b border-border px-4 py-3">
<h2 className="flex items-center gap-2 text-sm font-semibold tracking-tight">{title}</h2>
{extra}
</div>
{children}
</section>
);
}
export function Eyebrow({ children }: { children: ReactNode }) {
return <p className="mb-2 text-[10px] font-semibold uppercase tracking-widest text-muted-foreground">{children}</p>;
}
export function Success({ children }: { children: ReactNode }) {
return (
<span className="inline-flex items-center gap-1.5 text-xs text-emerald-600 dark:text-emerald-400">
<Check className="size-3.5" />
{children}
</span>
);
}
export function Note({ icon, children }: { icon: ReactNode; children: ReactNode }) {
return (
<div className="flex items-start gap-3 rounded-lg border border-border bg-muted/40 p-4 text-xs leading-relaxed text-muted-foreground">
<span className="mt-0.5 shrink-0">{icon}</span>
<div>{children}</div>
</div>
);
}

View file

@ -0,0 +1,246 @@
import type { FormEvent } from "react";
import { Button, Input, Tag } from "antd";
import { Check, Clock3, FileText, GitBranch, Search, ShieldCheck, ThumbsUp, X } from "lucide-react";
import { Eyebrow, Panel, Success } from "./SharedKnowledgePrimitives";
type JudgeStatus = "pending" | "accepted" | "rejected";
type Proposal = "supported" | "unsupported";
type SharedKnowledgeReviewProps = {
publishedTitle: string;
version: number;
proposalBaseVersion: number;
proposal: Proposal;
judge: JudgeStatus;
chooseProposal: (proposal: Proposal) => void;
onReview: () => void;
onOpenEvidence: () => void;
query: string;
onQueryChange: (query: string) => void;
onSearch: (event: FormEvent<HTMLFormElement>) => void;
hasMatch: boolean;
loaded: boolean;
outcome: boolean;
loadedVersion: number;
onLoad: () => void;
onHelpfulOutcome: () => void;
};
const judgeViews = {
accepted: {
className: "border-emerald-500/30 bg-emerald-500/5",
icon: Check,
iconClassName: "text-emerald-600 dark:text-emerald-400",
title: (version: number) => `Accepted · v${version} published`,
description:
"The query results support filtering before aggregation. The correction adds a verified child-account edge case.",
},
rejected: {
className: "border-amber-500/30 bg-amber-500/5",
icon: X,
iconClassName: "text-amber-600 dark:text-amber-400",
title: (version: number) => `Rejected · v${version} remains published`,
description: "The proposed change contradicts the query evidence. No new version is published.",
},
pending: {
className: "border-border bg-muted/40",
icon: Clock3,
iconClassName: "",
title: () => "Awaiting review",
description: "The published memo stays available while the proposed correction is checked.",
},
};
export function SharedKnowledgeReview({
publishedTitle,
version,
proposalBaseVersion,
proposal,
judge,
chooseProposal,
onReview,
onOpenEvidence,
query,
onQueryChange,
onSearch,
hasMatch,
loaded,
outcome,
loadedVersion,
onLoad,
onHelpfulOutcome,
}: SharedKnowledgeReviewProps) {
const judgeView = judgeViews[judge];
const JudgeIcon = judgeView.icon;
return (
<>
<div className="grid gap-4 lg:grid-cols-[1.2fr_1fr]">
<Panel
title={
<>
<GitBranch className="size-4 text-muted-foreground" />
Proposed correction
</>
}
extra={
<span className="font-mono text-xs text-muted-foreground">
v{proposalBaseVersion} → v{proposalBaseVersion + 1}
</span>
}
>
<div className="space-y-4 p-4">
<div>
<h3 className="text-sm font-semibold tracking-tight">{publishedTitle}</h3>
<p className="mt-1 text-xs text-muted-foreground">Proposed by Reconciliation agent · session b71c</p>
</div>
<div className="flex flex-wrap gap-2">
<Button
size="small"
type={proposal === "supported" ? "primary" : "default"}
disabled={version >= 2}
onClick={() => chooseProposal("supported")}
>
Evidence-backed Update
</Button>
<Button
size="small"
type={proposal === "unsupported" ? "primary" : "default"}
onClick={() => chooseProposal("unsupported")}
>
Try Unsupported Update
</Button>
</div>
<div className="overflow-hidden rounded-lg border border-border text-sm leading-relaxed">
<div className="border-b border-border bg-muted/50 p-3">
<Eyebrow>Current · v{proposalBaseVersion}</Eyebrow>
{proposalBaseVersion === 1
? "Filter to active accounts when calculating the total."
: "Filter inactive parent and child accounts before aggregation."}
</div>
<div className={`p-3 ${proposal === "supported" ? "bg-emerald-500/5" : "bg-amber-500/5"}`}>
<Eyebrow>Proposed · v{proposalBaseVersion + 1}</Eyebrow>
{proposal === "supported" ? (
<>
Filter inactive accounts <strong>before aggregation, including child accounts</strong>. A
parent-only filter can still overcount.
</>
) : (
<>Remove the active-account filter. All accounts should always be included.</>
)}
</div>
</div>
<Button size="small" type="text" icon={<FileText className="size-3.5" />} onClick={onOpenEvidence}>
Evidence: 3 Query Checks in Session b71c
</Button>
<div className="flex items-center gap-2 border-t border-border pt-3 text-xs text-muted-foreground">
<Clock3 className="size-3.5" />
Version history retained · {version > 1 ? `v1 → v${version} (current)` : "v1 remains current"}
</div>
</div>
</Panel>
<Panel
title={
<>
<ShieldCheck className="size-4 text-muted-foreground" />
Service-side LLM judge
</>
}
extra={<Tag>Simulated</Tag>}
>
<div className="space-y-4 p-4">
<p className="text-xs leading-relaxed text-muted-foreground">
A small model checks the correction against the current memo and its source evidence.
</p>
<ul className="space-y-3 text-sm">
<li className="flex items-center gap-2">
<ShieldCheck className="size-4 text-muted-foreground" />
Supported by the evidence
</li>
<li className="flex items-center gap-2">
<ShieldCheck className="size-4 text-muted-foreground" />
Consistent with the original scope
</li>
<li className="flex items-center gap-2">
<ShieldCheck className="size-4 text-muted-foreground" />
Specific enough to apply safely
</li>
</ul>
<div aria-live="polite" className={`rounded-lg border p-3 ${judgeView.className}`}>
<p className="flex items-center gap-2 text-sm font-medium">
<JudgeIcon className={`size-4 ${judgeView.iconClassName}`} />
{judgeView.title(version)}
</p>
<p className="mt-2 text-xs leading-relaxed text-muted-foreground">{judgeView.description}</p>
</div>
<Button
type="primary"
block
disabled={judge !== "pending"}
onClick={onReview}
icon={<ShieldCheck className="size-4" />}
>
Run Judge Review
</Button>
</div>
</Panel>
</div>
<Panel
title={
<>
<Search className="size-4 text-muted-foreground" />
The next agent finds the published memo
</>
}
extra={<span className="text-[11px] text-muted-foreground">Postgres · vector + text search</span>}
>
<div className="space-y-3 p-4">
<form onSubmit={onSearch} className="flex gap-2">
<Input
aria-label="Search shared knowledge"
prefix={<Search className="size-3.5 text-muted-foreground" />}
value={query}
onChange={(e) => onQueryChange(e.target.value)}
/>
<Button htmlType="submit">Search</Button>
</form>
{hasMatch ? (
<div className="flex flex-wrap items-center justify-between gap-3 rounded-lg border border-border bg-muted/30 p-3">
<div className="min-w-0">
<p className="text-sm font-medium">{publishedTitle}</p>
<p className="mt-1 text-xs text-muted-foreground">
v{version} · Semantic + keyword match · Account reporting
</p>
</div>
<Button onClick={onLoad} disabled={loaded}>
{loaded ? `v${version} Loaded` : `Load v${version} into Session`}
</Button>
</div>
) : (
<div className="flex flex-col items-center gap-2 py-4 text-center">
<Search className="size-6 text-muted-foreground" />
<p className="text-sm font-medium">No matching demo memos</p>
<p className="text-xs text-muted-foreground">Try “inactive accounts” or “reporting totals”.</p>
</div>
)}
{loaded && (
<div className="flex flex-wrap items-center justify-between gap-2" aria-live="polite">
<Success>
{outcome
? "Helpful outcome recorded · linked to this memo version"
: `Finance assistant loaded v${loadedVersion} into a different user’s session`}
</Success>
<Button
size="small"
disabled={outcome}
icon={<ThumbsUp className="size-3.5" />}
onClick={onHelpfulOutcome}
>
{outcome ? "Outcome Recorded" : "Record Helpful Outcome"}
</Button>
</div>
)}
</div>
</Panel>
</>
);
}

View file

@ -0,0 +1,38 @@
import { screen } from "@testing-library/react";
import { beforeEach, describe, expect, it, vi } from "vitest";
import { renderWithProviders, testQueryClient } from "../../../../../tests/test-utils";
import SharedKnowledgeDemoPage from "./page";
const { useAuthorizedMock } = vi.hoisted(() => ({ useAuthorizedMock: vi.fn() }));
vi.mock("@/app/(dashboard)/hooks/useAuthorized", () => ({ default: useAuthorizedMock }));
function renderAs(userRole: string) {
const session = { accessToken: "demo-token", userId: "demo-user", userRole, premiumUser: false };
useAuthorizedMock.mockReturnValue(session);
return renderWithProviders(<SharedKnowledgeDemoPage />, { searchParams: "?step=3" });
}
describe("Shared knowledge demo page access", () => {
beforeEach(() => {
testQueryClient.clear();
vi.clearAllMocks();
});
it("should render the requested demo step for an admin", () => {
renderAs("Admin");
expect(screen.getByRole("heading", { name: "Shared knowledge", exact: true })).toBeInTheDocument();
expect(screen.getByRole("heading", { name: "Review corrections. Share the better answer." })).toBeInTheDocument();
});
it.each(["Internal User", "Internal Viewer", "Org Admin", "Unknown Role"])(
"should show the Memory access notice instead of the demo for %s",
(userRole) => {
renderAs(userRole);
expect(screen.getByText("Memory is only available to admin users.")).toBeInTheDocument();
expect(screen.queryByRole("navigation", { name: "Demo steps" })).not.toBeInTheDocument();
},
);
});

View file

@ -0,0 +1,15 @@
"use client";
import useCan from "@/app/(dashboard)/hooks/useCan";
import { AdminOnlyNotice } from "@/components/shared/AdminOnlyNotice";
import SharedKnowledgeDemo from "./SharedKnowledgeDemo";
export default function SharedKnowledgeDemoPage() {
const canViewMemory = useCan("viewMemory");
if (!canViewMemory) {
return <AdminOnlyNotice pageTitle="Memory" />;
}
return <SharedKnowledgeDemo />;
}