@stigmer/react 3.4.0 → 3.5.0

package/src/agent/internal/__tests__/agentToInput.test.ts

@@ -0,0 +1,154 @@
+import { describe, it, expect } from "vitest";
+import { create, equals, isFieldSet, toJson } from "@bufbuild/protobuf";
+import type { Agent } from "@stigmer/protos/ai/stigmer/agentic/agent/v1/api_pb";
+import { AgentSchema } from "@stigmer/protos/ai/stigmer/agentic/agent/v1/api_pb";
+import { AgentSpecSchema } from "@stigmer/protos/ai/stigmer/agentic/agent/v1/spec_pb";
+import { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
+import { buildAgentProto } from "@stigmer/sdk";
+import { agentToInput } from "../agentToInput";
+
+/**
+ * Regression guard for stigmer/stigmer#319 — the console agent editor
+ * silently deleting `datastore_usages` on save.
+ *
+ * `agentToInput()` reconstructs a full `AgentInput` from a fetched Agent
+ * so inline edits can re-submit the whole spec (the backend does full
+ * spec replacement). Any spec field the converter does not map is
+ * therefore *cleared* by the next console edit. Two tests enforce the
+ * converter's "must be kept exhaustive" contract:
+ *
+ * 1. The round-trip test proves no field of the fixture below survives
+ *    conversion distorted or dropped.
+ * 2. The tripwire test proves the fixture itself covers every
+ *    `AgentSpec` field, via schema reflection. When a new proto field
+ *    lands, the tripwire fails until the fixture sets it — and the
+ *    round-trip then fails until `agentToInput()` maps it.
+ *
+ * Nested messages are covered by population, not reflection: every
+ * sub-field of the fixture (ref `version` pins, approval overrides,
+ * sub-agent grants, env metadata) must carry a non-default value so the
+ * round-trip comparison can catch its loss.
+ */
+function fullyPopulatedAgent(): Agent {
+  return create(AgentSchema, {
+    apiVersion: "agentic.stigmer.ai/v1",
+    kind: "Agent",
+    metadata: {
+      id: "agt_test",
+      name: "Clinic Assistant",
+      slug: "clinic-assistant",
+      org: "acme",
+      labels: { team: "care-ops" },
+    },
+    spec: {
+      description: "Front-desk assistant for the clinic pilot.",
+      iconUrl: "https://example.com/clinic.svg",
+      instructions: "You are a careful clinic assistant. Verify identity first.",
+      mcpServerUsages: [
+        {
+          mcpServerRef: {
+            org: "acme",
+            slug: "github",
+            kind: ApiResourceKind.mcp_server,
+          },
+          enabledTools: ["create_issue", "search_issues"],
+          toolApprovalOverrides: [
+            {
+              toolName: "create_issue",
+              requiresApproval: true,
+              message: "Create issue {{args.title}}?",
+            },
+          ],
+        },
+      ],
+      skillRefs: [
+        {
+          org: "acme",
+          slug: "triage-guide",
+          kind: ApiResourceKind.skill,
+          // The version pin (tag or hash) must survive conversion — a
+          // dropped pin silently resets the skill to "latest".
+          version: "stable",
+        },
+      ],
+      subAgents: [
+        {
+          name: "researcher",
+          description: "Looks up prior cases",
+          instructions: "Research thoroughly before answering anything.",
+          mcpAccess: [{ mcpServer: "github", enabledTools: ["search_issues"] }],
+          skillRefs: [
+            {
+              org: "acme",
+              slug: "research-methods",
+              kind: ApiResourceKind.skill,
+              version: "v1.2",
+            },
+          ],
+          modelOverride: "claude-sonnet",
+        },
+      ],
+      env: {
+        CLINIC_API_KEY: {
+          isSecret: true,
+          description: "Records bridge credential",
+        },
+        REGION: { optional: true },
+      },
+      datastoreUsages: [
+        {
+          datastoreRef: {
+            org: "acme",
+            slug: "clinic-records",
+            kind: ApiResourceKind.datastore,
+          },
+        },
+      ],
+    },
+  });
+}
+
+describe("agentToInput", () => {
+  it("round-trips a fully-populated spec through AgentInput without loss", () => {
+    const agent = fullyPopulatedAgent();
+
+    const rebuilt = buildAgentProto(agentToInput(agent));
+
+    // toJson gives a readable structural diff on failure; the protobuf
+    // equals() assertion below is the authoritative semantic check.
+    expect(toJson(AgentSpecSchema, rebuilt.spec!)).toEqual(
+      toJson(AgentSpecSchema, agent.spec!),
+    );
+    expect(equals(AgentSpecSchema, rebuilt.spec!, agent.spec!)).toBe(true);
+  });
+
+  it("round-trips the input-owned metadata fields", () => {
+    const agent = fullyPopulatedAgent();
+
+    const rebuilt = buildAgentProto(agentToInput(agent));
+
+    // Only the fields AgentInput owns: id is server-assigned, and
+    // visibility is deliberately unmapped (the backend preserves it on
+    // omit — see preserveImmutableFields in the update pipeline).
+    expect(rebuilt.metadata?.name).toBe(agent.metadata?.name);
+    expect(rebuilt.metadata?.org).toBe(agent.metadata?.org);
+    expect(rebuilt.metadata?.slug).toBe(agent.metadata?.slug);
+    expect(rebuilt.metadata?.labels).toEqual(agent.metadata?.labels);
+  });
+
+  it("populates every AgentSpec field in the fixture (new-field tripwire)", () => {
+    const spec = fullyPopulatedAgent().spec!;
+
+    const unsetFields = AgentSpecSchema.fields
+      .filter((field) => !isFieldSet(spec, field))
+      .map((field) => field.name);
+
+    expect(
+      unsetFields,
+      `AgentSpec gained field(s) [${unsetFields.join(", ")}] that the ` +
+        "fixture does not populate. Set them in fullyPopulatedAgent() AND " +
+        "map them in agentToInput() — an unmapped spec field is cleared " +
+        "by every console inline edit (stigmer/stigmer#319).",
+    ).toEqual([]);
+  });
+});

package/src/agent/internal/agentToInput.ts

@@ -1,16 +1,12 @@
 import type { Agent } from "@stigmer/protos/ai/stigmer/agentic/agent/v1/api_pb";
 import type {
   AgentInput,
+  DatastoreUsageInput,
+  EnvVarDeclarationInput,
   McpServerUsageInput,
   SubAgentInput,
 } from "@stigmer/sdk";
 
-interface EnvVarDeclarationInput {
-  isSecret?: boolean;
-  description?: string;
-  optional?: boolean;
-}
-
 /**
  * Converts a fetched Agent proto to the AgentInput shape expected by
  * `stigmer.agent.update()`. This enables inline field editing: read the
@@ -18,16 +14,23 @@ interface EnvVarDeclarationInput {
  *
  * Must be kept exhaustive — any spec field not mapped here will be
  * cleared on the next update (the backend does full spec replacement).
+ * Enforced by `__tests__/agentToInput.test.ts`: a schema tripwire fails
+ * when `AgentSpec` gains a field this converter does not round-trip
+ * (stigmer/stigmer#319 was exactly such a drop).
  */
 export function agentToInput(agent: Agent): AgentInput {
   const meta = agent.metadata;
   const spec = agent.spec;
 
+  // Resource refs preserve `version` (the tag/hash pin on versioned
+  // resources like Skills) — dropping it would silently reset a pinned
+  // reference to "latest" on the next inline edit.
   const mcpServerUsages: McpServerUsageInput[] | undefined =
     spec?.mcpServerUsages?.map((usage) => ({
       mcpServerRef: {
         org: usage.mcpServerRef?.org ?? "",
         slug: usage.mcpServerRef?.slug ?? "",
+        version: usage.mcpServerRef?.version || undefined,
       },
       enabledTools: usage.enabledTools.length > 0 ? [...usage.enabledTools] : undefined,
       toolApprovalOverrides:
@@ -44,6 +47,7 @@ export function agentToInput(agent: Agent): AgentInput {
     spec?.skillRefs?.map((ref) => ({
       org: ref.org || "",
       slug: ref.slug,
+      version: ref.version || undefined,
     }));
 
   const subAgents: SubAgentInput[] | undefined =
@@ -60,11 +64,24 @@ export function agentToInput(agent: Agent): AgentInput {
           : undefined,
       skillRefs:
         sa.skillRefs.length > 0
-          ? sa.skillRefs.map((r) => ({ org: r.org || "", slug: r.slug }))
+          ? sa.skillRefs.map((r) => ({
+              org: r.org || "",
+              slug: r.slug,
+              version: r.version || undefined,
+            }))
           : undefined,
       modelOverride: sa.modelOverride || undefined,
     }));
 
+  const datastoreUsages: DatastoreUsageInput[] | undefined =
+    spec?.datastoreUsages?.map((usage) => ({
+      datastoreRef: {
+        org: usage.datastoreRef?.org ?? "",
+        slug: usage.datastoreRef?.slug ?? "",
+        version: usage.datastoreRef?.version || undefined,
+      },
+    }));
+
   let env: Record<string, EnvVarDeclarationInput> | undefined;
   if (spec?.env && Object.keys(spec.env).length > 0) {
     env = {};
@@ -91,5 +108,6 @@ export function agentToInput(agent: Agent): AgentInput {
     skillRefs: skillRefs?.length ? skillRefs : undefined,
     subAgents: subAgents?.length ? subAgents : undefined,
     env,
+    datastoreUsages: datastoreUsages?.length ? datastoreUsages : undefined,
   };
 }

package/src/agent/useAgentCount.ts

@@ -17,6 +17,8 @@ export interface UseAgentCountOptions {
    * @default "org"
    */
   readonly scope?: ResourceListScope;
+  /** Opaque token that forces a recount when its value changes. */
+  readonly refetchToken?: unknown;
 }
 
 /** Return value of {@link useAgentCount}. */

package/src/api-key/ApiKeyListPanel.tsx

@@ -18,6 +18,13 @@ export interface ApiKeyListPanelProps {
   readonly onRefetchRef?: (refetch: () => void) => void;
   /** Additional CSS class names for the root container. */
   readonly className?: string;
+  /**
+   * Reference instant for the "last used" relative stamp. Defaults to
+   * the live clock. **Deterministic hosts (documentation embeds, video
+   * export) must pass a frozen instant** — otherwise a depicted key's
+   * "2h ago" drifts with every replay.
+   */
+  readonly now?: Date;
 }
 
 /**
@@ -46,6 +53,7 @@ export interface ApiKeyListPanelProps {
 export function ApiKeyListPanel({
   onRefetchRef,
   className,
+  now,
 }: ApiKeyListPanelProps) {
   const { apiKeys, isLoading, error, refetch } = useApiKeyList();
   const [confirmingId, setConfirmingId] = useState<string | null>(null);
@@ -104,6 +112,7 @@ export function ApiKeyListPanel({
           <ApiKeyRow
             key={id}
             apiKey={key}
+            now={now}
             isConfirming={confirmingId === id}
             onConfirmDelete={() => setConfirmingId(id)}
             onCancelDelete={() => setConfirmingId(null)}
@@ -124,12 +133,14 @@ export function ApiKeyListPanel({
 
 function ApiKeyRow({
   apiKey,
+  now,
   isConfirming,
   onConfirmDelete,
   onCancelDelete,
   onDeleted,
 }: {
   apiKey: ApiKey;
+  now?: Date;
   isConfirming: boolean;
   onConfirmDelete: () => void;
   onCancelDelete: () => void;
@@ -243,7 +254,9 @@ function ApiKeyRow({
               : "No expiry"}
         </span>
         <span>
-          {lastUsedAt ? formatRelativeTime(timestampDate(lastUsedAt)) : "Never used"}
+          {lastUsedAt
+            ? formatRelativeTime(timestampDate(lastUsedAt), now)
+            : "Never used"}
         </span>
       </div>
 
@@ -276,9 +289,9 @@ function formatShortDate(date: Date): string {
   });
 }
 
-function formatRelativeTime(date: Date): string {
-  const now = Date.now();
-  const diffMs = now - date.getTime();
+function formatRelativeTime(date: Date, now?: Date): string {
+  const ref = now?.getTime() ?? Date.now();
+  const diffMs = ref - date.getTime();
 
   if (diffMs < 0) return "Just now";
 

package/src/api-key/CreateApiKeyForm.tsx

@@ -22,6 +22,12 @@ export interface CreateApiKeyFormProps {
   readonly onCreated?: (apiKey: ApiKey) => void;
   /** Fired when the user cancels creation. */
   readonly onCancel?: () => void;
+  /**
+   * Seeds the name field on mount (e.g. a suggested key name, or a demo
+   * scenario depicting the form mid-fill). One-time: consumed on mount;
+   * subsequent changes are ignored. The field stays fully editable.
+   */
+  readonly initialName?: string;
   /** Additional CSS class names for the root container. */
   readonly className?: string;
 }
@@ -51,11 +57,12 @@ export function CreateApiKeyForm({
   org,
   onCreated,
   onCancel,
+  initialName = "",
   className,
 }: CreateApiKeyFormProps) {
   const { create, isCreating, error, clearError } = useCreateApiKey();
 
-  const [name, setName] = useState("");
+  const [name, setName] = useState(initialName);
   const [expiry, setExpiry] = useState<ExpiryOption>("never");
 
   const trimmedName = name.trim();

package/src/api-key/__tests__/CreateApiKeyForm.test.tsx

@@ -0,0 +1,58 @@
+import { describe, it, expect, vi, afterEach } from "vitest";
+import { render, screen, fireEvent, cleanup } from "@testing-library/react";
+import type { ReactNode } from "react";
+import type { Stigmer } from "@stigmer/sdk";
+import { StigmerContext } from "../../context";
+import { CreateApiKeyForm } from "../CreateApiKeyForm";
+
+afterEach(cleanup);
+
+function createWrapper() {
+  const mockClient = {
+    apiKey: { create: vi.fn() },
+  } as unknown as Stigmer;
+
+  return ({ children }: { children: ReactNode }) => (
+    <StigmerContext.Provider value={mockClient}>
+      {children}
+    </StigmerContext.Provider>
+  );
+}
+
+function nameInput(): HTMLInputElement {
+  return screen.getByLabelText("Name") as HTMLInputElement;
+}
+
+function submitButton(): HTMLButtonElement {
+  return screen.getByRole("button", {
+    name: "Create API key",
+  }) as HTMLButtonElement;
+}
+
+describe("CreateApiKeyForm initialName", () => {
+  it("starts with an empty name and a disabled submit by default", () => {
+    render(<CreateApiKeyForm org="acme" />, { wrapper: createWrapper() });
+
+    expect(nameInput().value).toBe("");
+    expect(submitButton().disabled).toBe(true);
+  });
+
+  it("seeds the name field and enables submit when initialName is set", () => {
+    render(<CreateApiKeyForm org="acme" initialName="quickstart-key" />, {
+      wrapper: createWrapper(),
+    });
+
+    expect(nameInput().value).toBe("quickstart-key");
+    expect(submitButton().disabled).toBe(false);
+  });
+
+  it("keeps the seeded field editable — initialName is a seed, not a lock", () => {
+    render(<CreateApiKeyForm org="acme" initialName="quickstart-key" />, {
+      wrapper: createWrapper(),
+    });
+
+    fireEvent.change(nameInput(), { target: { value: "renamed-key" } });
+
+    expect(nameInput().value).toBe("renamed-key");
+  });
+});

package/src/datastore/useDatastoreCount.ts

@@ -17,6 +17,8 @@ export interface UseDatastoreCountOptions {
    * @default "org"
    */
   readonly scope?: ResourceListScope;
+  /** Opaque token that forces a recount when its value changes. */
+  readonly refetchToken?: unknown;
 }
 
 /** Return value of {@link useDatastoreCount}. */

package/src/dependency-graph/DependencyTreeNode.tsx

@@ -2,6 +2,7 @@
 
 import { useCallback, useState, type KeyboardEvent } from "react";
 import { cn } from "@stigmer/theme";
+import { DatastoreIcon } from "../datastore/DatastoreDetailView.js";
 import type { DependencyNode, NodeKind } from "./types.js";
 
 interface DependencyTreeNodeProps {
@@ -15,6 +16,7 @@ const KIND_LABELS: Record<NodeKind, string> = {
   agent: "Agent",
   "mcp-server": "MCP",
   skill: "Skill",
+  datastore: "Datastore",
   "sub-agent": "Sub-Agent",
 };
 
@@ -179,6 +181,10 @@ function kindBadgeClasses(kind: NodeKind): string {
       return "bg-[var(--stgm-status-running-subtle)] text-[var(--stgm-status-running)]";
     case "skill":
       return "bg-[var(--stgm-status-pending-subtle)] text-[var(--stgm-status-pending)]";
+    // Badges borrow status hues as category colors (skill=pending,
+    // sub-agent=ready); datastore takes the remaining distinct hue.
+    case "datastore":
+      return "bg-[var(--stgm-status-degraded-subtle)] text-[var(--stgm-status-degraded)]";
     case "sub-agent":
       return "bg-[var(--stgm-status-ready-subtle)] text-[var(--stgm-status-ready)]";
     case "agent":
@@ -205,6 +211,8 @@ function NodeIcon({
       return <McpServerIcon className={className} />;
     case "skill":
       return <SkillIcon className={className} />;
+    case "datastore":
+      return <DatastoreIcon className={className} />;
   }
 }
 

package/src/dependency-graph/__tests__/useDependencyGraph.test.ts

@@ -0,0 +1,108 @@
+import { describe, it, expect } from "vitest";
+import { renderHook } from "@testing-library/react";
+import { useDependencyGraph } from "../useDependencyGraph";
+
+const emptySpec = {
+  mcpServerUsages: [],
+  skillRefs: [],
+  subAgents: [],
+};
+
+function graphFor(spec: Parameters<typeof useDependencyGraph>[0]["spec"]) {
+  const { result } = renderHook(() =>
+    useDependencyGraph({ agentName: "clinic-assistant", agentOrg: "acme", spec }),
+  );
+  return result.current;
+}
+
+describe("useDependencyGraph — datastore nodes", () => {
+  it("derives a datastore node with a navigation ref", () => {
+    const { tree, isEmpty } = graphFor({
+      ...emptySpec,
+      datastoreUsages: [
+        { datastoreRef: { org: "acme", slug: "clinic-records" } },
+      ],
+    });
+
+    // A datastore-only agent has dependencies — the tab must appear.
+    expect(isEmpty).toBe(false);
+    expect(tree).not.toBeNull();
+    expect(tree!.nodeCount).toBe(2);
+
+    const node = tree!.root.children[0];
+    expect(node).toMatchObject({
+      id: "datastore:clinic-records",
+      kind: "datastore",
+      label: "clinic-records",
+      ref: { org: "acme", slug: "clinic-records" },
+    });
+    // Same-org ref gets no qualified label.
+    expect(node.qualifiedLabel).toBeUndefined();
+  });
+
+  it("qualifies cross-org datastore labels and falls back to the agent org for empty refs", () => {
+    const { tree } = graphFor({
+      ...emptySpec,
+      datastoreUsages: [
+        { datastoreRef: { org: "partner", slug: "shared-records" } },
+        { datastoreRef: { org: "", slug: "local-records" } },
+      ],
+    });
+
+    const [crossOrg, relative] = tree!.root.children;
+    expect(crossOrg.qualifiedLabel).toBe("partner/shared-records");
+    expect(crossOrg.ref).toEqual({ org: "partner", slug: "shared-records" });
+    expect(relative.qualifiedLabel).toBeUndefined();
+    expect(relative.ref).toEqual({ org: "acme", slug: "local-records" });
+  });
+
+  it("orders children to mirror the Overview sections: MCP, skills, datastores, sub-agents", () => {
+    const { tree } = graphFor({
+      mcpServerUsages: [
+        {
+          mcpServerRef: { org: "acme", slug: "github" },
+          enabledTools: [],
+          toolApprovalOverrides: [],
+        },
+      ],
+      skillRefs: [{ org: "acme", slug: "triage-guide" }],
+      subAgents: [
+        {
+          name: "researcher",
+          description: "",
+          mcpAccess: [],
+          skillRefs: [],
+          modelOverride: "",
+        },
+      ],
+      datastoreUsages: [
+        { datastoreRef: { org: "acme", slug: "clinic-records" } },
+      ],
+    });
+
+    expect(tree!.root.children.map((c) => c.kind)).toEqual([
+      "mcp-server",
+      "skill",
+      "datastore",
+      "sub-agent",
+    ]);
+    expect(tree!.nodeCount).toBe(5);
+  });
+
+  it("accepts specs without the datastoreUsages field (pre-existing public callers)", () => {
+    const { tree, isEmpty } = graphFor({
+      ...emptySpec,
+      skillRefs: [{ org: "acme", slug: "triage-guide" }],
+    });
+
+    expect(isEmpty).toBe(false);
+    expect(tree!.root.children.map((c) => c.kind)).toEqual(["skill"]);
+  });
+
+  it("stays empty when no dependencies exist at all", () => {
+    const { tree, isEmpty } = graphFor({ ...emptySpec, datastoreUsages: [] });
+
+    expect(isEmpty).toBe(true);
+    expect(tree).toBeNull();
+  });
+});

package/src/dependency-graph/types.ts

@@ -4,9 +4,10 @@
  * - `"agent"` — the root agent (always the tree root)
  * - `"mcp-server"` — an MCP server referenced via `mcpServerUsages` or `mcpAccess`
  * - `"skill"` — a skill referenced via `skillRefs`
+ * - `"datastore"` — a datastore referenced via `datastoreUsages`
  * - `"sub-agent"` — an inline sub-agent definition with its own dependencies
  */
-export type NodeKind = "agent" | "mcp-server" | "skill" | "sub-agent";
+export type NodeKind = "agent" | "mcp-server" | "skill" | "datastore" | "sub-agent";
 
 /**
  * A single node in the agent dependency tree.
@@ -15,9 +16,9 @@ export type NodeKind = "agent" | "mcp-server" | "skill" | "sub-agent";
  * (MCP servers and skills they access). Edges are implicit in the
  * parent-child relationship — no separate edge type is needed.
  *
- * Nodes are navigable when `ref` is defined (MCP servers, skills).
- * Sub-agent nodes have no `ref` because they are inline definitions
- * within the agent spec, not standalone resources.
+ * Nodes are navigable when `ref` is defined (MCP servers, skills,
+ * datastores). Sub-agent nodes have no `ref` because they are inline
+ * definitions within the agent spec, not standalone resources.
  */
 export interface DependencyNode {
   /**
@@ -46,9 +47,9 @@ export interface DependencyNode {
   /** Child nodes. Empty array for leaf nodes (MCP servers, skills). */
   readonly children: readonly DependencyNode[];
   /**
-   * Navigation reference for clickable nodes. Defined for MCP servers
-   * and skills (standalone resources). Undefined for sub-agents (inline
-   * definitions) and the root agent.
+   * Navigation reference for clickable nodes. Defined for MCP servers,
+   * skills, and datastores (standalone resources). Undefined for
+   * sub-agents (inline definitions) and the root agent.
    */
   readonly ref?: { readonly org: string; readonly slug: string };
 }
@@ -70,7 +71,7 @@ export interface DependencyGraphProps {
   /**
    * Called when a navigable node is clicked. The `node.ref` field
    * contains the `org` and `slug` for routing. Only fired for nodes
-   * where `ref` is defined (MCP servers, skills).
+   * where `ref` is defined (MCP servers, skills, datastores).
    */
   readonly onNodeClick?: (node: DependencyNode) => void;
   /**
@@ -119,6 +120,17 @@ export interface UseDependencyGraphOptions {
       }[];
       readonly modelOverride: string;
     }[];
+    /**
+     * Datastore attachments (`spec.datastoreUsages`). Optional because
+     * this hook is a public SDK export: callers passing hand-built spec
+     * objects written before the field existed must keep compiling.
+     */
+    readonly datastoreUsages?: readonly {
+      readonly datastoreRef?: {
+        readonly org: string;
+        readonly slug: string;
+      };
+    }[];
   } | undefined;
 }
 

package/src/dependency-graph/useDependencyGraph.ts

@@ -41,10 +41,12 @@ export function useDependencyGraph({
     if (!spec) return { tree: null, isEmpty: true };
 
     const { mcpServerUsages, skillRefs, subAgents } = spec;
+    const datastoreUsages = spec.datastoreUsages ?? [];
 
     const hasDeps =
       mcpServerUsages.length > 0 ||
       skillRefs.length > 0 ||
+      datastoreUsages.length > 0 ||
       subAgents.length > 0;
 
     if (!hasDeps) return { tree: null, isEmpty: true };
@@ -92,6 +94,24 @@ export function useDependencyGraph({
       };
     });
 
+    const datastoreNodes: DependencyNode[] = datastoreUsages
+      .filter((u) => u.datastoreRef)
+      .map((usage) => {
+        nodeCount++;
+        const ref = usage.datastoreRef!;
+        return {
+          id: `datastore:${ref.slug}`,
+          kind: "datastore" as const,
+          label: ref.slug,
+          qualifiedLabel:
+            ref.org && ref.org !== agentOrg
+              ? `${ref.org}/${ref.slug}`
+              : undefined,
+          children: [],
+          ref: { org: ref.org || agentOrg, slug: ref.slug },
+        };
+      });
+
     const subAgentNodes: DependencyNode[] = subAgents.map((sa) => {
       nodeCount++;
 
@@ -143,11 +163,13 @@ export function useDependencyGraph({
       };
     });
 
+    // Child ordering mirrors the Overview sections: MCP servers,
+    // skills, datastores, then sub-agents.
     const root: DependencyNode = {
       id: `agent:${agentName}`,
       kind: "agent",
       label: agentName,
-      children: [...mcpNodes, ...skillNodes, ...subAgentNodes],
+      children: [...mcpNodes, ...skillNodes, ...datastoreNodes, ...subAgentNodes],
     };
 
     return {