@stigmer/react 3.4.1 → 3.5.0

package/src/agent/__tests__/AgentDetailView.datastores.test.tsx

@@ -0,0 +1,166 @@
+// Tests for the Datastores section on AgentDetailView (stigmer/stigmer#319):
+// read-mode rendering and navigation, the inline-edit save payload (which
+// must round-trip the full spec through agentToInput), and the DD-006
+// surfacing of the backend's datastore exposure guard refusal.
+
+import { describe, it, expect, vi, beforeAll, afterEach, beforeEach, type Mock } from "vitest";
+import { render, screen, cleanup, waitFor } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import type { ReactNode } from "react";
+import { create } from "@bufbuild/protobuf";
+import { AgentSchema } from "@stigmer/protos/ai/stigmer/agentic/agent/v1/api_pb";
+import { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
+import type { AgentInput } from "@stigmer/sdk";
+import { StigmerContext } from "../../context";
+import { FetchCacheContext } from "../../internal/FetchCacheProvider";
+import { AgentDetailView } from "../AgentDetailView";
+
+beforeAll(() => {
+  HTMLDialogElement.prototype.showModal = function showModal() {
+    this.open = true;
+  };
+  HTMLDialogElement.prototype.close = function close() {
+    this.open = false;
+  };
+});
+
+afterEach(() => cleanup());
+beforeEach(() => vi.restoreAllMocks());
+
+function makeAgent() {
+  return create(AgentSchema, {
+    metadata: {
+      id: "agt_1",
+      name: "Clinic Assistant",
+      slug: "clinic-assistant",
+      org: "acme",
+    },
+    spec: {
+      instructions: "You are a careful clinic assistant.",
+      datastoreUsages: [
+        {
+          datastoreRef: {
+            org: "acme",
+            slug: "clinic-records",
+            kind: ApiResourceKind.datastore,
+          },
+        },
+        {
+          datastoreRef: {
+            org: "partner",
+            slug: "shared-records",
+            kind: ApiResourceKind.datastore,
+          },
+        },
+      ],
+    },
+  });
+}
+
+function renderView(overrides: {
+  update?: Mock;
+  onDatastoreClick?: (ref: { org: string; slug: string }) => void;
+  editable?: boolean;
+}) {
+  const agent = makeAgent();
+  const update = overrides.update ?? vi.fn().mockResolvedValue(agent);
+  const stigmer = {
+    agent: {
+      getByReference: vi.fn().mockResolvedValue(agent),
+      update,
+    },
+    iamPolicy: {
+      checkMyPermission: vi.fn().mockResolvedValue({ isAuthorized: false }),
+    },
+  };
+
+  function Wrapper({ children }: { children: ReactNode }) {
+    return (
+      <FetchCacheContext.Provider value={null}>
+        <StigmerContext.Provider value={stigmer as never}>
+          {children}
+        </StigmerContext.Provider>
+      </FetchCacheContext.Provider>
+    );
+  }
+
+  const result = render(
+    <AgentDetailView
+      org="acme"
+      slug="clinic-assistant"
+      editable={overrides.editable}
+      onDatastoreClick={overrides.onDatastoreClick}
+    />,
+    { wrapper: Wrapper },
+  );
+  return { ...result, update };
+}
+
+describe("AgentDetailView — Datastores section (read mode)", () => {
+  it("renders attached datastores with org-qualified labels for cross-org refs", async () => {
+    renderView({});
+
+    expect(await screen.findByText("Datastores")).toBeTruthy();
+    expect(screen.getByText("clinic-records")).toBeTruthy();
+    expect(screen.getByText("partner/shared-records")).toBeTruthy();
+  });
+
+  it("fires onDatastoreClick with the resolved org and slug", async () => {
+    const user = userEvent.setup();
+    const onDatastoreClick = vi.fn();
+    renderView({ onDatastoreClick });
+
+    await user.click(await screen.findByText("clinic-records"));
+    expect(onDatastoreClick).toHaveBeenCalledWith({
+      org: "acme",
+      slug: "clinic-records",
+    });
+
+    await user.click(screen.getByText("partner/shared-records"));
+    expect(onDatastoreClick).toHaveBeenCalledWith({
+      org: "partner",
+      slug: "shared-records",
+    });
+  });
+});
+
+describe("AgentDetailView — Datastores section (inline edit)", () => {
+  it("saves the full reconstructed input with correctly-shaped datastoreUsages", async () => {
+    const user = userEvent.setup();
+    const { update } = renderView({ editable: true });
+
+    await user.click(await screen.findByLabelText("Edit datastores"));
+    await user.click(screen.getByLabelText("Remove partner/shared-records"));
+    await user.click(screen.getByRole("button", { name: "Save changes" }));
+
+    await waitFor(() => expect(update).toHaveBeenCalledTimes(1));
+    const input = update.mock.calls[0][0] as AgentInput;
+
+    expect(input.datastoreUsages).toEqual([
+      { datastoreRef: { org: "acme", slug: "clinic-records" } },
+    ]);
+    // The rest of the spec must ride along — a section save is a full
+    // spec replacement reconstructed via agentToInput().
+    expect(input.instructions).toBe("You are a careful clinic assistant.");
+    expect(input.org).toBe("acme");
+    expect(input.slug).toBe("clinic-assistant");
+  });
+
+  it("surfaces the backend's exposure-guard refusal in the section editor (DD-006)", async () => {
+    const user = userEvent.setup();
+    const guardMessage =
+      'agent "clinic-assistant" cannot be public while it uses datastores ' +
+      "(clinic-records): multi-tenant datastore sharing is not supported — " +
+      "keep the agent private or org-visible, or remove its datastore_usages";
+    renderView({
+      editable: true,
+      update: vi.fn().mockRejectedValue(new Error(guardMessage)),
+    });
+
+    await user.click(await screen.findByLabelText("Edit datastores"));
+    await user.click(screen.getByRole("button", { name: "Save changes" }));
+
+    const alert = await screen.findByRole("alert");
+    expect(alert.textContent).toContain(guardMessage);
+  });
+});

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/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/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;
 }