@polpo-ai/dashboard 0.1.0

package/LICENSE

@@ -0,0 +1,13 @@
+Copyright 2026-present Lumea Labs
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

package/README.md

@@ -0,0 +1,44 @@
+# @polpo-ai/dashboard
+
+The self-hosted Polpo dashboard — the single-instance debugger UI for one Polpo
+server: agents, tasks, missions, sessions, memory, skills, playbooks, schedules,
+storage, logs and a chat playground.
+
+It talks to your Polpo server through the public SDK (`@polpo-ai/sdk`). There is
+no auth, billing, org or onboarding here — those are cloud-only. One server, one
+dashboard.
+
+## Run it
+
+You need a running Polpo server (the data plane). Then:
+
+```bash
+cp .env.example .env.local      # point NEXT_PUBLIC_API_URL at your server
+pnpm install
+pnpm dev                        # http://localhost:3000
+```
+
+`/` redirects to `/projects/local/agents`. `local` is a placeholder project id —
+single-tenant self-host has one project, and the data client ignores the id.
+
+## Config
+
+| Env var | Default | What |
+| --- | --- | --- |
+| `NEXT_PUBLIC_API_URL` | `http://localhost:4000` | Your Polpo server base URL |
+| `NEXT_PUBLIC_POLPO_API_PREFIX` | `/api/v1` | API root the server mounts under (the standalone server serves at `/api/v1`) |
+| `NEXT_PUBLIC_POLPO_API_KEY` | — | `sk_...` key for the server (optional if it runs without auth) |
+
+## How the data layer works
+
+Views address the data plane by path (`/v1/agents`, `/v1/tasks`, …). `lib/data-client.ts`
+drives a single `PolpoClient` from `@polpo-ai/sdk` (transport, auth, errors) and
+re-wraps the result in the `{ ok, data }` envelope the views expect. Swapping the
+server is just `NEXT_PUBLIC_API_URL`.
+
+## Not wired yet
+
+A few shell/settings surfaces still reach for cloud-only control-plane endpoints
+(project name, BYOK keys, billing). These are gated to single-tenant stubs so the
+dashboard runs; see the `TODO` in `lib/data-client.ts`. BYOK will be re-pointed to
+the data-plane `vault` route.

package/app/(dashboard)/error.tsx

@@ -0,0 +1,47 @@
+"use client";
+
+/**
+ * Error boundary for the dashboard group. A transient backend failure
+ * (control-plane 5xx / network / DB unreachable) now surfaces here instead
+ * of being swallowed into "no orgs → /onboarding". Auth failures (401) are
+ * handled upstream by `getOrgs` (redirect to /login).
+ */
+export default function DashboardError({
+  error,
+  reset,
+}: {
+  error: Error & { digest?: string };
+  reset: () => void;
+}) {
+  return (
+    <div className="flex min-h-[60vh] items-center justify-center p-6">
+      <div className="w-full max-w-md border border-border bg-card p-8 text-center">
+        <h2 className="text-base font-semibold text-foreground">Something went wrong</h2>
+        <p className="mt-2 text-sm text-muted-foreground">
+          We couldn&apos;t reach the control plane. This is usually temporary —
+          give it a moment and retry.
+        </p>
+        {error?.digest ? (
+          <p className="mt-3 font-mono text-[11px] text-muted-foreground/50">
+            ref: {error.digest}
+          </p>
+        ) : null}
+        <div className="mt-6 flex items-center justify-center gap-3">
+          <button
+            type="button"
+            onClick={() => reset()}
+            className="border border-foreground bg-foreground px-4 py-2 text-sm font-medium text-background transition-colors hover:bg-foreground/90"
+          >
+            Try again
+          </button>
+          <a
+            href="/login"
+            className="border border-border px-4 py-2 text-sm font-medium text-foreground transition-colors hover:border-foreground/40"
+          >
+            Sign in
+          </a>
+        </div>
+      </div>
+    </div>
+  );
+}

package/app/(dashboard)/layout.tsx

@@ -0,0 +1,41 @@
+import { Sidebar, MobileSidebar, MobileHeader } from "#/components/dashboard/sidebar";
+import { TopHeader } from "#/components/dashboard/top-header";
+import { Providers } from "#/components/providers";
+import { MobileSidebarProvider } from "#/hooks/use-mobile-sidebar";
+import { DesktopSidebarProvider } from "#/hooks/use-desktop-sidebar";
+import { CopilotLayout } from "#/components/dashboard/project-copilot";
+
+/**
+ * Single-tenant self-host shell. No Better Auth session, no org list, no
+ * onboarding gate — those live only in the cloud build. One local instance,
+ * straight into the dashboard chrome.
+ */
+export default function DashboardLayout({
+  children,
+}: {
+  children: React.ReactNode;
+}) {
+  return (
+    <Providers>
+      <MobileSidebarProvider>
+        <DesktopSidebarProvider>
+          <div className="flex h-screen flex-col overflow-hidden">
+            <div className="hidden md:block">
+              <TopHeader />
+            </div>
+
+            <div className="flex flex-1 overflow-hidden">
+              <Sidebar />
+              <MobileSidebar />
+
+              <div className="flex flex-1 flex-col overflow-hidden">
+                <MobileHeader />
+                <CopilotLayout>{children}</CopilotLayout>
+              </div>
+            </div>
+          </div>
+        </DesktopSidebarProvider>
+      </MobileSidebarProvider>
+    </Providers>
+  );
+}

package/app/(dashboard)/loading.tsx

@@ -0,0 +1,30 @@
+export default function DashboardLoading() {
+  return (
+    <div className="px-4 py-6 md:px-8 md:py-8">
+      <div className="space-y-4">
+        {/* Header skeleton */}
+        <div className="h-8 w-48 animate-pulse rounded bg-muted" />
+        <div className="h-4 w-80 animate-pulse rounded bg-muted/60" />
+
+        {/* Content skeleton */}
+        <div className="mt-8 grid gap-4 md:grid-cols-2 lg:grid-cols-4">
+          {Array.from({ length: 4 }).map((_, i) => (
+            <div
+              key={i}
+              className="h-24 animate-pulse rounded-lg border border-border bg-card"
+            />
+          ))}
+        </div>
+
+        <div className="mt-8 space-y-3">
+          {Array.from({ length: 5 }).map((_, i) => (
+            <div
+              key={i}
+              className="h-12 animate-pulse rounded border border-border bg-card"
+            />
+          ))}
+        </div>
+      </div>
+    </div>
+  );
+}

package/app/(dashboard)/projects/[id]/agents/[name]/memory/view.tsx

@@ -0,0 +1,36 @@
+import Link from "next/link";
+import { Markdown } from "#/components/dashboard/markdown";
+import { CopyButton } from "#/components/dashboard/copy-button";
+import { Hint } from "#/components/dashboard/hint";
+
+export default function AgentMemoryView({ id, content }: { id: string; content: string }) {
+  return (
+    <div>
+      <div className="mb-4">
+        <Hint action={content ? <CopyButton value={content} label="Copy" className="shrink-0" /> : undefined}>
+          Private memory this agent accumulates across sessions. It also inherits the
+          shared project memory.
+        </Hint>
+      </div>
+
+      {content ? (
+        <div data-testid="agent-memory-content" className="border border-border bg-card p-6">
+          <Markdown content={content} />
+        </div>
+      ) : (
+        <div className="border border-border p-8 text-center text-sm text-muted-foreground">
+          No memory yet. Memory is created automatically when the agent works.
+        </div>
+      )}
+
+      <div className="mt-4">
+        <Link
+          href={`/projects/${id}/memory`}
+          className="text-xs text-muted-foreground hover:text-foreground transition-colors"
+        >
+          View shared project memory &rarr;
+        </Link>
+      </div>
+    </div>
+  );
+}

package/app/(dashboard)/projects/[id]/agents/[name]/models-view.tsx

@@ -0,0 +1,30 @@
+import type { AgentConfig } from "@polpo-ai/core";
+import { AgentCapabilities } from "#/components/dashboard/agent-capabilities";
+
+/** Models tab — the per-capability model grid (one row per modality). */
+export default function AgentModelsView({
+  agent,
+  projectId,
+  agentName,
+}: {
+  agent: AgentConfig | null;
+  projectId: string;
+  agentName: string;
+}) {
+  if (!agent) {
+    return (
+      <div
+        data-testid="agent-not-found"
+        className="mt-4 border border-border p-8 text-center text-sm text-muted-foreground"
+      >
+        Agent not found.
+      </div>
+    );
+  }
+
+  return (
+    <section className="pt-2">
+      <AgentCapabilities agent={agent} projectId={projectId} agentName={agentName} />
+    </section>
+  );
+}

package/app/(dashboard)/projects/[id]/agents/[name]/page.tsx

@@ -0,0 +1,51 @@
+import { Suspense } from "react";
+import { dataApi, getAgent } from "#/lib/api";
+import { AgentProfileSkeleton } from "#/components/dashboard/skeletons";
+import { AgentStudio, type VaultEntry } from "#/components/dashboard/agent-studio";
+
+const API_URL = process.env.NEXT_PUBLIC_API_URL ?? "http://localhost:4000";
+
+async function AgentData({ id, name }: { id: string; name: string }) {
+  // The agent detail IS the Studio (chat canvas). Fetch everything its
+  // tabs need (agent + memory + vault) up front, server-side.
+  const [agent, memoryContent, vaultEntries] = await Promise.all([
+    getAgent(id, name),
+    dataApi<{ ok: boolean; data: { content: string } }>(
+      id,
+      `/v1/memory/agent/${encodeURIComponent(name)}`,
+    )
+      .then((r) => r.data?.content ?? "")
+      .catch(() => ""),
+    dataApi<{ ok: boolean; data: VaultEntry[] }>(
+      id,
+      `/v1/vault/entries/${encodeURIComponent(name)}`,
+    )
+      .then((r) => r.data ?? [])
+      .catch(() => [] as VaultEntry[]),
+  ]);
+
+  return (
+    <AgentStudio
+      projectId={id}
+      apiUrl={API_URL}
+      agent={agent}
+      memoryContent={memoryContent}
+      vaultEntries={vaultEntries}
+    />
+  );
+}
+
+export default async function AgentDetailPage({
+  params,
+}: {
+  params: Promise<{ id: string; name: string }>;
+}) {
+  const { id, name } = await params;
+  const decodedName = decodeURIComponent(name);
+
+  return (
+    <Suspense fallback={<AgentProfileSkeleton />}>
+      <AgentData id={id} name={decodedName} />
+    </Suspense>
+  );
+}

package/app/(dashboard)/projects/[id]/agents/[name]/prompt/view.tsx

@@ -0,0 +1,211 @@
+"use client";
+
+import { useState } from "react";
+import { Eye } from "lucide-react";
+import type { AgentConfig } from "@polpo-ai/core";
+import { Markdown } from "#/components/dashboard/markdown";
+import { CopyButton } from "#/components/dashboard/copy-button";
+import { Hint } from "#/components/dashboard/hint";
+import {
+  Dialog,
+  DialogContent,
+  DialogDescription,
+  DialogHeader,
+  DialogTitle,
+} from "#/components/ui/dialog";
+
+const API_URL = process.env.NEXT_PUBLIC_API_URL ?? "http://localhost:4000";
+
+/** Rough token estimate — ~4 chars/token, good enough for a budget hint. */
+const approxTokens = (s: string) => Math.round(s.length / 4);
+
+export default function AgentPromptView({
+  agent,
+  projectId,
+  agentName,
+}: {
+  agent: AgentConfig | null;
+  projectId: string;
+  agentName: string;
+}) {
+  if (!agent) {
+    return (
+      <div className="mt-4 border border-border p-8 text-center text-sm text-muted-foreground">
+        Agent not found.
+      </div>
+    );
+  }
+
+  const instructions = agent.systemPrompt ?? "";
+  const chars = instructions.length;
+
+  return (
+    <div>
+      <Hint action={<PreviewButton projectId={projectId} agentName={agentName} />}>
+        Extra instructions added on top of the agent&apos;s base prompt — they shape
+        tone and rules without replacing Polpo&apos;s defaults. Hit Preview for the
+        full composed prompt.
+      </Hint>
+
+      {instructions ? (
+        <>
+          <div className="mt-2 flex items-center gap-2">
+            <span className="inline-flex items-center gap-1 border border-border bg-secondary/40 px-2 py-0.5 font-mono text-[11px] font-medium text-foreground">
+              {chars.toLocaleString()}
+              <span className="text-muted-foreground">chars</span>
+            </span>
+            <span className="inline-flex items-center gap-1 border border-border bg-secondary/40 px-2 py-0.5 font-mono text-[11px] font-medium text-foreground">
+              ~{approxTokens(instructions).toLocaleString()}
+              <span className="text-muted-foreground">tokens</span>
+            </span>
+          </div>
+          <div className="mt-3 border border-border bg-card p-6">
+            <Markdown content={instructions} />
+          </div>
+        </>
+      ) : (
+        <div className="mt-3 border border-border p-8 text-center">
+          <p className="text-sm text-muted-foreground">No extra instructions configured.</p>
+          <p className="mt-1 text-xs text-muted-foreground">
+            This agent runs on the default base prompt. Preview it to see what that includes.
+          </p>
+        </div>
+      )}
+    </div>
+  );
+}
+
+/**
+ * Loading state for the prompt preview — a sharp skeleton that mimics the
+ * composed prompt materialising (metadata bar + paragraph blocks of
+ * varying width), in keeping with the rest of the surface.
+ */
+function PromptSkeleton() {
+  // Width pattern per "paragraph" — last line of each block is shorter,
+  // so it reads as real prose rather than a uniform block.
+  const blocks = [
+    ["w-1/3"],
+    ["w-full", "w-full", "w-11/12", "w-2/3"],
+    ["w-full", "w-5/6", "w-full", "w-1/2"],
+    ["w-3/4", "w-full", "w-4/5"],
+  ];
+  let line = 0;
+  return (
+    <div className="flex min-h-0 flex-1 flex-col">
+      <div className="flex items-center justify-between gap-4 border-y border-border py-2">
+        <span className="h-3 w-40 animate-pulse bg-muted" />
+        <span className="h-6 w-16 animate-pulse bg-muted" />
+      </div>
+      <div className="min-h-0 flex-1 space-y-5 overflow-hidden bg-card p-4">
+        {blocks.map((widths, b) => (
+          <div key={b} className="space-y-2">
+            {widths.map((w) => {
+              const delay = (line++ % 6) * 90;
+              return (
+                <div
+                  key={w + line}
+                  className={`h-3 ${w} animate-pulse bg-muted`}
+                  style={{ animationDelay: `${delay}ms` }}
+                />
+              );
+            })}
+          </div>
+        ))}
+      </div>
+      <p className="border-t border-border pt-2 font-mono text-[11px] text-muted-foreground/60">
+        Composing the full prompt…
+      </p>
+    </div>
+  );
+}
+
+/**
+ * Preview — fetches the FULLY composed system prompt from the data plane
+ * (`GET /v1/agents/:name/prompt`), which runs the same `buildAgentSystemPrompt`
+ * + skill-loading the runtime uses. Shows the exact text sent to the model.
+ */
+function PreviewButton({
+  projectId,
+  agentName,
+}: {
+  projectId: string;
+  agentName: string;
+}) {
+  const [open, setOpen] = useState(false);
+  const [loading, setLoading] = useState(false);
+  const [prompt, setPrompt] = useState<string | null>(null);
+  const [error, setError] = useState<string | null>(null);
+
+  async function load() {
+    setOpen(true);
+    setLoading(true);
+    setError(null);
+    setPrompt(null);
+    try {
+      const res = await fetch(
+        `${API_URL}/v1/projects/${projectId}/data/v1/agents/${encodeURIComponent(agentName)}/prompt`,
+        { credentials: "include" },
+      );
+      const body = await res.json().catch(() => ({}));
+      if (!res.ok || !body.ok) {
+        setError(body.error ?? `Failed to compose prompt (${res.status})`);
+      } else {
+        setPrompt(body.data?.prompt ?? "");
+      }
+    } catch (err) {
+      setError((err as Error).message ?? "Failed to compose prompt");
+    }
+    setLoading(false);
+  }
+
+  return (
+    <>
+      <button
+        type="button"
+        onClick={() => void load()}
+        className="inline-flex shrink-0 items-center gap-1.5 border border-border bg-card px-2.5 py-1.5 text-xs font-medium text-muted-foreground transition-colors hover:border-foreground/30 hover:text-foreground"
+      >
+        <Eye className="h-3.5 w-3.5" strokeWidth={1.5} />
+        Preview
+      </button>
+
+      <Dialog open={open} onOpenChange={setOpen}>
+        <DialogContent className="flex max-h-[85vh] flex-col overflow-hidden sm:max-w-3xl">
+          <DialogHeader>
+            <DialogTitle>Composed system prompt</DialogTitle>
+            <DialogDescription>
+              The complete prompt the platform sends to the model — base prompt,
+              identity, your instructions and loaded skills, exactly as the
+              runtime composes it.
+            </DialogDescription>
+          </DialogHeader>
+
+          {loading ? (
+            <PromptSkeleton />
+          ) : error ? (
+            <p className="py-6 text-sm text-destructive">{error}</p>
+          ) : prompt !== null ? (
+            <>
+              <div className="flex items-center justify-between gap-4 border-y border-border py-2">
+                <div className="flex items-center gap-2">
+                  <span className="inline-flex items-center gap-1 border border-border bg-secondary/40 px-2 py-0.5 font-mono text-[11px] font-medium text-foreground">
+                    {prompt.length.toLocaleString()}
+                    <span className="text-muted-foreground">chars</span>
+                  </span>
+                  <span className="inline-flex items-center gap-1 border border-border bg-secondary/40 px-2 py-0.5 font-mono text-[11px] font-medium text-foreground">
+                    ~{approxTokens(prompt).toLocaleString()}
+                    <span className="text-muted-foreground">tokens</span>
+                  </span>
+                </div>
+                <CopyButton value={prompt} label="Copy" className="shrink-0" />
+              </div>
+              <div className="min-h-0 flex-1 overflow-auto bg-card p-4">
+                <Markdown content={prompt} />
+              </div>
+            </>
+          ) : null}
+        </DialogContent>
+      </Dialog>
+    </>
+  );
+}

package/app/(dashboard)/projects/[id]/agents/[name]/skills/view.tsx

@@ -0,0 +1,84 @@
+import Link from "next/link";
+import type { AgentConfig } from "@polpo-ai/core";
+import { BookMarked, ExternalLink } from "lucide-react";
+import { SectionHeader } from "#/components/dashboard/section-header";
+
+export default function AgentSkillsView({
+  agent,
+  projectId,
+}: {
+  agent: AgentConfig | null;
+  projectId: string;
+}) {
+  if (!agent) {
+    return (
+      <div
+        data-testid="agent-not-found"
+        className="border border-border p-8 text-center text-sm text-muted-foreground"
+      >
+        Agent not found.
+      </div>
+    );
+  }
+
+  const skills = agent.skills ?? [];
+
+  return (
+    <div>
+      <SectionHeader
+        description={
+          <>
+            Installed skills extend this agent with reusable procedures. Manage
+            them with <span className="font-mono">polpo install</span> or in the
+            agent config <span className="font-mono">skills</span> field.
+          </>
+        }
+      />
+
+      {skills.length === 0 ? (
+        <div className="mt-4 border border-dashed border-border p-8 text-center">
+          <BookMarked
+            className="mx-auto h-5 w-5 text-muted-foreground/40"
+            strokeWidth={1.5}
+          />
+          <p className="mt-2 text-sm text-muted-foreground">No skills installed.</p>
+          <p className="mt-1 text-xs text-muted-foreground/60">
+            Browse the catalog at{" "}
+            <a
+              href="https://docs.polpo.sh/docs/agents/skills"
+              target="_blank"
+              rel="noopener noreferrer"
+              className="underline decoration-dotted underline-offset-2 transition-colors hover:text-foreground"
+            >
+              docs.polpo.sh
+            </a>
+            .
+          </p>
+        </div>
+      ) : (
+        <div className="mt-4 grid grid-cols-1 gap-3 sm:grid-cols-2 lg:grid-cols-3">
+          {skills.map((skill) => (
+            <Link
+              key={skill}
+              href={`/projects/${projectId}/skills/${encodeURIComponent(skill)}`}
+              target="_blank"
+              rel="noopener noreferrer"
+              className="group flex items-center gap-2.5 border border-border bg-card p-3 transition-colors hover:border-foreground/30"
+            >
+              <span className="grid size-7 shrink-0 place-items-center bg-secondary text-muted-foreground">
+                <BookMarked className="h-3.5 w-3.5" strokeWidth={1.5} />
+              </span>
+              <span className="min-w-0 flex-1 truncate font-mono text-sm text-foreground">
+                {skill}
+              </span>
+              <ExternalLink
+                className="h-3.5 w-3.5 shrink-0 text-muted-foreground/40 transition-colors group-hover:text-foreground"
+                strokeWidth={1.5}
+              />
+            </Link>
+          ))}
+        </div>
+      )}
+    </div>
+  );
+}