Skip to content

armgit / eve

Public Imported from GitHub
0

The Open Framework for Building Agents

fix(docs): render the runtime diagram in Markdown exports (#4245)

Colton Padden72069e05e260
diff --git a/apps/docs/components/geistdocs/agent-runtime-diagram.tsx b/apps/docs/components/geistdocs/agent-runtime-diagram.tsx
index 024a2070d..6beb0f0fb 100644
--- a/apps/docs/components/geistdocs/agent-runtime-diagram.tsx
+++ b/apps/docs/components/geistdocs/agent-runtime-diagram.tsx
@@ -7,8 +7,18 @@ import {
IconWrench,
} from "@vercel/geistdocs/assets/icons";
import type { JSX, ReactNode } from "react";
+import { agentRuntimeDiagram, type CardId } from "@/lib/geistdocs/agent-runtime-diagram";
import { cn } from "@/lib/utils";
+const cardPresentation: Record<CardId, { icon: ReactNode; className?: string }> = {
+ "agent-loop": { icon: <IconWorkflow size={18} /> },
+ "runtime-code": { icon: <IconWrench size={18} /> },
+ credentials: { icon: <IconLinked size={18} /> },
+ skills: { icon: <IconFileText size={18} />, className: "order-2 lg:order-1" },
+ "sandbox-operations": { icon: <IconSandbox size={18} />, className: "order-1 lg:order-2" },
+ workspace: { icon: <IconFolderOpen size={18} />, className: "order-3" },
+};
+
function Environment({
title,
description,
@@ -41,7 +51,7 @@ function RuntimeCard({
icon: ReactNode;
title: string;
description: string;
- paths?: string[];
+ paths?: readonly string[];
className?: string;
}): JSX.Element {
return (
@@ -73,7 +83,7 @@ function SandboxBridge(): JSX.Element {
/>
<div className="relative rounded-lg border border-gray-alpha-700 bg-background-100 px-3 py-2 text-center shadow-sm">
<code className="bg-transparent! p-0! font-medium text-copy-13! text-gray-1000!">
- ctx.getSandbox()
+ {agentRuntimeDiagram.bridge}
</code>
</div>
</div>
@@ -89,58 +99,19 @@ export function AgentRuntimeDiagram(): JSX.Element {
aria-label="Agent loop and sandbox execution boundary"
className="my-8 grid w-full min-w-0 items-stretch gap-4 lg:grid-cols-[minmax(0,1fr)_160px_minmax(0,1fr)]"
>
- <Environment title="Trusted app runtime" description="Full Node.js access and credentials">
- <RuntimeCard
- icon={<IconWorkflow size={18} />}
- title="Agent loop"
- description="Durable workflow, model calls, and orchestration"
- paths={["agent/agent.ts", "agent/instructions.md"]}
- />
- <RuntimeCard
- icon={<IconWrench size={18} />}
- title="Runtime code"
- description="Tools, hooks, instrumentation, and connections"
- paths={[
- "agent/tools/**",
- "agent/hooks/**",
- "agent/instrumentation/**",
- "agent/connections/**",
- ]}
- />
- <RuntimeCard
- icon={<IconLinked size={18} />}
- title="Secrets and credentials"
- description="Provider keys, tool secrets, and MCP/OpenAPI auth stay here"
- />
+ <Environment {...agentRuntimeDiagram.runtime}>
+ {agentRuntimeDiagram.runtime.cards.map((card) => (
+ <RuntimeCard key={card.id} {...card} {...cardPresentation[card.id]} />
+ ))}
</Environment>
<SandboxBridge />
- <Environment
- title="Isolated sandbox"
- description="Filesystem and processes without app secrets"
- >
+ <Environment {...agentRuntimeDiagram.sandbox}>
<div className="grid gap-3">
- <RuntimeCard
- icon={<IconFileText size={18} />}
- title="Skills"
- description="Materialized for the agent"
- paths={["$HOME/.agents/skills", "from agent/skills/**"]}
- className="order-2 lg:order-1"
- />
- <RuntimeCard
- icon={<IconSandbox size={18} />}
- title="Sandbox operations"
- description="Shell commands, file access, scripts, and servers"
- className="order-1 lg:order-2"
- />
- <RuntimeCard
- icon={<IconFolderOpen size={18} />}
- title="Workspace"
- description="Persistent per-session files"
- paths={["/workspace", "from agent/sandbox/workspace/**"]}
- className="order-3"
- />
+ {agentRuntimeDiagram.sandbox.cards.map((card) => (
+ <RuntimeCard key={card.id} {...card} {...cardPresentation[card.id]} />
+ ))}
</div>
</Environment>
</figure>
diff --git a/apps/docs/lib/geistdocs/agent-runtime-diagram.ts b/apps/docs/lib/geistdocs/agent-runtime-diagram.ts
new file mode 100644
index 000000000..e2a37abe7
--- /dev/null
+++ b/apps/docs/lib/geistdocs/agent-runtime-diagram.ts
@@ -0,0 +1,80 @@
+export const agentRuntimeDiagram = {
+ runtime: {
+ title: "Trusted app runtime",
+ description: "Full Node.js access and credentials",
+ cards: [
+ {
+ id: "agent-loop",
+ title: "Agent loop",
+ description: "Durable workflow, model calls, and orchestration",
+ paths: ["agent/agent.ts", "agent/instructions.md"],
+ },
+ {
+ id: "runtime-code",
+ title: "Runtime code",
+ description: "Tools, hooks, instrumentation, and connections",
+ paths: [
+ "agent/tools/**",
+ "agent/hooks/**",
+ "agent/instrumentation/**",
+ "agent/connections/**",
+ ],
+ },
+ {
+ id: "credentials",
+ title: "Secrets and credentials",
+ description: "Provider keys, tool secrets, and MCP/OpenAPI auth stay here",
+ },
+ ],
+ },
+ bridge: "ctx.getSandbox()",
+ sandbox: {
+ title: "Isolated sandbox",
+ description: "Filesystem and processes without app secrets",
+ cards: [
+ {
+ id: "skills",
+ title: "Skills",
+ description: "Materialized for the agent",
+ paths: ["$HOME/.agents/skills", "from agent/skills/**"],
+ },
+ {
+ id: "sandbox-operations",
+ title: "Sandbox operations",
+ description: "Shell commands, file access, scripts, and servers",
+ },
+ {
+ id: "workspace",
+ title: "Workspace",
+ description: "Persistent per-session files",
+ paths: ["/workspace", "from agent/sandbox/workspace/**"],
+ },
+ ],
+ },
+} as const;
+
+export type CardId = (typeof agentRuntimeDiagram)["runtime" | "sandbox"]["cards"][number]["id"];
+
+function renderEnvironment(environment: {
+ title: string;
+ description: string;
+ cards: readonly { title: string; description: string; paths?: readonly string[] }[];
+}): string {
+ return [
+ `**${environment.title}** — ${environment.description}`,
+ ...environment.cards.map(
+ (card) =>
+ `- **${card.title}** — ${card.description}${
+ card.paths ? `\n${card.paths.map((path) => ` - \`${path}\``).join("\n")}` : ""
+ }`,
+ ),
+ ].join("\n\n");
+}
+
+export function renderAgentRuntimeDiagramMarkdown(): string {
+ return [
+ renderEnvironment(agentRuntimeDiagram.runtime),
+ `App runtime → \`${agentRuntimeDiagram.bridge}\` → sandbox`,
+ renderEnvironment(agentRuntimeDiagram.sandbox),
+ ].join("\n\n");
+}
diff --git a/apps/docs/lib/geistdocs/remark-component-markdown.test.ts b/apps/docs/lib/geistdocs/remark-component-markdown.test.ts
new file mode 100644
index 000000000..5a1ae091e
--- /dev/null
+++ b/apps/docs/lib/geistdocs/remark-component-markdown.test.ts
@@ -0,0 +1,62 @@
+import { createProcessor } from "@mdx-js/mdx";
+import { toMarkdown, type Options } from "mdast-util-to-markdown";
+import { describe, expect, it } from "vitest";
+import config from "../../source.config";
+
+describe("component Markdown export", () => {
+ it("expands the runtime diagram without changing HTML or component examples", async () => {
+ const options =
+ typeof config.mdxOptions === "function" ? await config.mdxOptions() : config.mdxOptions;
+ const plugins = options?.remarkPlugins;
+ if (!Array.isArray(plugins)) throw new Error("Expected configured remark plugins");
+ const processor = createProcessor({ remarkPlugins: plugins });
+ const source = [
+ "## Agent loop and sandbox",
+ "",
+ "<AgentRuntimeDiagram />",
+ "",
+ "<Callout>Keep this content.</Callout>",
+ "",
+ "```mdx",
+ "<AgentRuntimeDiagram />",
+ "```",
+ ].join("\n");
+ const tree = processor.parse(source);
+ const markdown = toMarkdown(tree, {
+ extensions: (processor.data() as { toMarkdownExtensions?: Options[] }).toMarkdownExtensions,
+ });
+
+ expect(markdown).toContain("**Trusted app runtime** — Full Node.js access and credentials");
+ expect(markdown).toContain("**Agent loop** — Durable workflow, model calls, and orchestration");
+ expect(markdown).toContain("`agent/agent.ts`");
+ expect(markdown).toContain("`agent/instructions.md`");
+ expect(markdown).toContain("**Runtime code** — Tools, hooks, instrumentation, and connections");
+ expect(markdown).toContain("`agent/tools/**`");
+ expect(markdown).toContain("`agent/hooks/**`");
+ expect(markdown).toContain("`agent/instrumentation/**`");
+ expect(markdown).toContain("`agent/connections/**`");
+ expect(markdown).toContain(
+ "**Secrets and credentials** — Provider keys, tool secrets, and MCP/OpenAPI auth stay here",
+ );
+ expect(markdown).toContain("`ctx.getSandbox()`");
+ expect(markdown).toContain(
+ "**Isolated sandbox** — Filesystem and processes without app secrets",
+ );
+ expect(markdown).toContain("**Skills** — Materialized for the agent");
+ expect(markdown).toContain("`$HOME/.agents/skills`");
+ expect(markdown).toContain("`from agent/skills/**`");
+ expect(markdown).toContain(
+ "**Sandbox operations** — Shell commands, file access, scripts, and servers",
+ );
+ expect(markdown).toContain("**Workspace** — Persistent per-session files");
+ expect(markdown).toContain("`/workspace`");
+ expect(markdown).toContain("`from agent/sandbox/workspace/**`");
+ expect(markdown).toContain("<Callout>Keep this content.</Callout>");
+ expect(markdown).toContain("```mdx\n<AgentRuntimeDiagram />\n```");
+ expect(markdown.match(/<AgentRuntimeDiagram \/>/g)).toHaveLength(1);
+
+ expect(tree.children).toContainEqual(
+ expect.objectContaining({ type: "mdxJsxFlowElement", name: "AgentRuntimeDiagram" }),
+ );
+ });
+});
diff --git a/apps/docs/lib/geistdocs/remark-component-markdown.ts b/apps/docs/lib/geistdocs/remark-component-markdown.ts
new file mode 100644
index 000000000..2abfd1694
--- /dev/null
+++ b/apps/docs/lib/geistdocs/remark-component-markdown.ts
@@ -0,0 +1,18 @@
+import { mdxJsxToMarkdown } from "mdast-util-mdx-jsx";
+import type { Options } from "mdast-util-to-markdown";
+import { renderAgentRuntimeDiagramMarkdown } from "./agent-runtime-diagram";
+
+// Customize serialization only: the MDX tree must keep the visual component for HTML.
+export function remarkComponentMarkdown(this: { data(): unknown }): void {
+ const data = this.data() as { toMarkdownExtensions?: Options[] };
+ const extensions = (data.toMarkdownExtensions ??= []);
+ const fallback = mdxJsxToMarkdown().handlers!.mdxJsxFlowElement!;
+ extensions.push({
+ handlers: {
+ mdxJsxFlowElement(node, parent, state, info) {
+ if (node.name === "AgentRuntimeDiagram") return renderAgentRuntimeDiagramMarkdown();
+ return fallback(node, parent, state, info);
+ },
+ },
+ });
+}
diff --git a/apps/docs/package.json b/apps/docs/package.json
index 0eddbdbcc..7425630db 100644
--- a/apps/docs/package.json
+++ b/apps/docs/package.json
@@ -69,6 +69,7 @@
"@kybernesis/arcana": "0.4.1",
"@larksuite/vercel-chat-adapter": "0.1.2",
"@liveblocks/chat-sdk-adapter": "3.23.0",
+ "@mdx-js/mdx": "3.1.1",
"@novu/chat-sdk-adapter": "0.1.0",
"@onkernel/eve-extension": "^0.1.3",
"@opentelemetry/api": "1.9.1",
@@ -99,6 +100,8 @@
"chat-adapter-sendblue": "0.2.0",
"eve": "workspace:*",
"eve-channel-blooio": "0.2.0",
+ "mdast-util-mdx-jsx": "3.2.0",
+ "mdast-util-to-markdown": "2.1.2",
"portless": "0.15.6",
"postcss": "8.5.15",
"shadcn": "4.16.0",
diff --git a/apps/docs/source.config.ts b/apps/docs/source.config.ts
index 5235d0227..5e2ce6950 100644
--- a/apps/docs/source.config.ts
+++ b/apps/docs/source.config.ts
@@ -6,6 +6,7 @@ import {
import { remarkMdxMermaid } from "fumadocs-core/mdx-plugins";
import { defineConfig, defineDocs } from "fumadocs-mdx/config";
import lastModified, { type LastModifiedPluginOptions } from "fumadocs-mdx/plugins/last-modified";
+import { remarkComponentMarkdown } from "./lib/geistdocs/remark-component-markdown";
// Some docs use non-standard fenced code labels like
// `\`\`\`384:401:path/to/file.ts` (line range + file path instead of a
@@ -57,7 +58,7 @@ const lastModifiedVersionControl: LastModifiedPluginOptions["versionControl"] =
// git-backed last-modified lookup when the deployment checkout is shallow.
export default defineConfig({
mdxOptions: {
- remarkPlugins: [remarkMdxMermaid, remarkNormalizeCodeLang],
+ remarkPlugins: [remarkMdxMermaid, remarkNormalizeCodeLang, remarkComponentMarkdown],
rehypeCodeOptions: {
themes: {
light: geistShikiTheme,
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index be3afa4d2..7b9d6e55f 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -444,6 +444,9 @@ importers:
'@liveblocks/chat-sdk-adapter':
specifier: 3.23.0
+ '@mdx-js/mdx':
+ specifier: 3.1.1
+ version: 3.1.1([email protected])
'@novu/chat-sdk-adapter':
specifier: 0.1.0
@@ -534,6 +537,12 @@ importers:
eve-channel-blooio:
specifier: 0.2.0
version: 0.2.0([email protected]([email protected]))(eve@packages+eve)
+ mdast-util-mdx-jsx:
+ specifier: 3.2.0
+ version: 3.2.0([email protected])
+ mdast-util-to-markdown:
+ specifier: 2.1.2
+ version: 2.1.2
portless:
specifier: 0.15.6
version: 0.15.6