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.tsxindex 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.jsonindex 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.tsindex 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.yamlindex be3afa4d2..7b9d6e55f 100644--- a/pnpm-lock.yaml+++ b/pnpm-lock.yaml@@ -444,6 +444,9 @@ importers:'@liveblocks/chat-sdk-adapter':specifier: 3.23.0version: 3.23.0(@types/[email protected])([email protected]([email protected]([email protected]))([email protected])([email protected]))+ '@mdx-js/mdx':+ specifier: 3.1.1+ version: 3.1.1([email protected])'@novu/chat-sdk-adapter':specifier: 0.1.0version: 0.1.0([email protected]([email protected]))([email protected]([email protected]([email protected]))([email protected])([email protected]))([email protected])([email protected])([email protected])@@ -534,6 +537,12 @@ importers:eve-channel-blooio:specifier: 0.2.0version: 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.2portless:specifier: 0.15.6version: 0.15.6