@stigmer/mcp-server 3.3.0 → 3.4.0

package/src/domains/agentexecutions/approve.ts

@@ -0,0 +1,67 @@
+// Agent-execution approval path: submit a decision for a tool call the
+// execution is waiting on (AgentExecutionCommandController.submitApproval).
+//
+// Pending approvals surface in get_agent_execution's
+// status.pending_approvals[] — there is no org-wide inbox for agent
+// executions (that exists only for workflow human_input tasks, see
+// workflowexecutions/approvals.ts). The response reuses the compact
+// projection: the returned AgentExecution embeds the full message history,
+// which the approval loop doesn't need.
+
+import { ApprovalAction } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+import { AgentExecutionCommandController } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/command_pb";
+
+import { withClient } from "../client.js";
+import { rpcError } from "../rpcerr.js";
+import { compactExecutionJson, DEFAULT_MESSAGE_LIMIT } from "./fetch.js";
+
+/**
+ * Model-facing action spelling → proto enum. APPROVE_ALL is deliberately not
+ * exposed: blanket auto-approval is a run-configuration concern, not a
+ * per-decision one.
+ */
+const APPROVAL_ACTIONS: Readonly<Record<string, ApprovalAction>> = {
+  approve: ApprovalAction.APPROVE,
+  skip: ApprovalAction.SKIP,
+  reject: ApprovalAction.REJECT,
+};
+
+export interface SubmitAgentApprovalArgs {
+  readonly executionId: string;
+  readonly toolCallId: string;
+  readonly action: string;
+  readonly comment?: string;
+}
+
+/** Submit an approval decision; returns the execution in the compact view. */
+export async function submitAgentApproval(
+  serverAddress: string,
+  token: string,
+  args: SubmitAgentApprovalArgs,
+): Promise<string> {
+  const action = APPROVAL_ACTIONS[args.action];
+  if (action === undefined) {
+    throw new Error(`unknown action "${args.action}"; valid actions: approve, skip, reject`);
+  }
+  return withClient(
+    AgentExecutionCommandController,
+    serverAddress,
+    token,
+    async (client, callOptions) => {
+      try {
+        const execution = await client.submitApproval(
+          {
+            agentExecutionId: args.executionId,
+            toolCallId: args.toolCallId,
+            action,
+            comment: args.comment ?? "",
+          },
+          callOptions,
+        );
+        return compactExecutionJson(execution, DEFAULT_MESSAGE_LIMIT);
+      } catch (err) {
+        throw rpcError(err, `approval for agent execution "${args.executionId}"`);
+      }
+    },
+  );
+}

package/src/domains/agentexecutions/fetch.ts

@@ -0,0 +1,112 @@
+// Agent-execution read path: the polling primitive behind get_agent_execution.
+//
+// Agent executions have no event-log RPC (unlike workflow executions) — the
+// platform's contract is: poll get and read status.phase, status.messages[],
+// and status.pending_approvals[]. That makes the response shape critical for
+// MCP: a long conversation's full protojson (every message, the resolved
+// context snapshot, the approval ledger, sub-agent transcripts) can dwarf the
+// model's context. The default "compact" view therefore returns a bounded
+// message tail and drops the bulky server-side bookkeeping fields; "full" is
+// the verbatim protojson for when the model genuinely needs everything.
+
+import { AgentExecutionSchema, type AgentExecution } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/api_pb";
+import { AgentExecutionQueryController } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/query_pb";
+
+import { withClient } from "../client.js";
+import { toProtoJson } from "../marshal.js";
+import { rpcError } from "../rpcerr.js";
+
+export type ExecutionView = "compact" | "full";
+
+/** Message-tail size when the caller doesn't specify one. */
+export const DEFAULT_MESSAGE_LIMIT = 5;
+
+/**
+ * Bulky status fields pruned from the compact view. These are server-side
+ * bookkeeping (resolved-resource snapshot, append-only approval ledger,
+ * Temporal callback token) and sub-agent transcripts — none of which the
+ * poll loop (phase? messages? approvals?) needs.
+ */
+const COMPACT_PRUNED_STATUS_FIELDS = [
+  "resolved_context",
+  "approval_events",
+  "callback_token",
+  "sub_agent_executions",
+] as const;
+
+/** Fetch a single agent execution by ID and shape it for the requested view. */
+export async function fetchAgentExecution(
+  serverAddress: string,
+  token: string,
+  executionId: string,
+  view: ExecutionView,
+  messageLimit: number,
+): Promise<string> {
+  if (executionId === "") {
+    throw new Error("execution_id is required");
+  }
+  return withClient(
+    AgentExecutionQueryController,
+    serverAddress,
+    token,
+    async (client, callOptions) => {
+      let execution: AgentExecution;
+      try {
+        execution = await client.get({ value: executionId }, callOptions);
+      } catch (err) {
+        throw rpcError(err, `agent execution "${executionId}"`);
+      }
+      return view === "full"
+        ? toProtoJson(AgentExecutionSchema, execution)
+        : compactExecutionJson(execution, messageLimit);
+    },
+  );
+}
+
+/** The compact projection plus the pre-truncation message count. */
+export interface CompactExecution {
+  readonly totalMessages: number;
+  readonly data: Record<string, unknown>;
+}
+
+/**
+ * Build the compact projection: full protojson minus the pruned status
+ * fields, with status.messages sliced to the last `messageLimit` entries.
+ * Exposed at the data level so wrappers (cancel_execution's already_terminal
+ * envelope) can compose it without double-nesting.
+ *
+ * Shared by the write tools that return an AgentExecution (approve, cancel):
+ * their responses embed the same potentially-huge status.
+ */
+export function compactExecution(execution: AgentExecution, messageLimit: number): CompactExecution {
+  const data = JSON.parse(toProtoJson(AgentExecutionSchema, execution)) as Record<string, unknown>;
+  let totalMessages = 0;
+
+  const status = data.status as Record<string, unknown> | undefined;
+  if (status !== undefined) {
+    const messages: unknown[] = Array.isArray(status.messages) ? status.messages : [];
+    totalMessages = messages.length;
+    if (messages.length > messageLimit) {
+      status.messages = messages.slice(-messageLimit);
+    }
+    for (const field of COMPACT_PRUNED_STATUS_FIELDS) {
+      delete status[field];
+    }
+  }
+
+  return { totalMessages, data };
+}
+
+/**
+ * The compact view as returned by tools: a wrapper carrying total_messages so
+ * the model can tell when the message tail is a window (and re-request with a
+ * larger message_limit or view=full).
+ */
+export function compactExecutionJson(execution: AgentExecution, messageLimit: number): string {
+  const { totalMessages, data } = compactExecution(execution, messageLimit);
+  return JSON.stringify(
+    { view: "compact", total_messages: totalMessages, execution: data },
+    null,
+    2,
+  );
+}

package/src/domains/agentexecutions/run.ts

@@ -0,0 +1,112 @@
+// Agent-execution start path for the run_agent tool.
+//
+// Mirrors the CLI's run stack (client-apps/cli/src/resources/run/create.ts):
+// starting an agent is a single AgentExecutionCommandController.create call —
+// the server bootstraps the session, resolves the agent's default instance
+// (auto-creating if missing), and dispatches the message. The MCP layer only
+// resolves the org/slug reference to the agent ID first, over the same
+// transport (the two-step pattern the delete tools use).
+//
+// The tool is deliberately asynchronous: it returns the created execution
+// (with its aex_* ID) immediately and the run continues in the background.
+// Observation happens through get_agent_execution polling — MCP tools are
+// request/response, so there is no streaming path here by design.
+
+import { createClient } from "@connectrpc/connect";
+import { create as createMessage } from "@bufbuild/protobuf";
+import { AgentQueryController } from "@stigmer/protos/ai/stigmer/agentic/agent/v1/query_pb";
+import { AgentExecutionSchema } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/api_pb";
+import { AgentExecutionCommandController } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/command_pb";
+import { AgentExecutionSpecSchema } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/spec_pb";
+import {
+  ExecutionValueSchema,
+  type ExecutionValue,
+} from "@stigmer/protos/ai/stigmer/agentic/executioncontext/v1/spec_pb";
+import { ApiResourceMetadataSchema } from "@stigmer/protos/ai/stigmer/commons/apiresource/metadata_pb";
+import { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
+
+import { withTransport } from "../client.js";
+import { toProtoJson } from "../marshal.js";
+import { rpcError } from "../rpcerr.js";
+
+/** apiVersion stamped on created executions; mirrors the CLI's run stack. */
+const API_VERSION = "agentic.stigmer.ai/v1";
+
+export interface RunAgentArgs {
+  readonly org: string;
+  readonly agent: string;
+  readonly message: string;
+  readonly sessionId?: string;
+  readonly runtimeEnv?: Record<string, string>;
+}
+
+/**
+ * Start an agent execution: resolve org/slug → agent ID, then create the
+ * execution. Returns the created execution as protojson (small at creation
+ * time — status is empty until the runner picks it up).
+ */
+export async function runAgent(
+  serverAddress: string,
+  token: string,
+  args: RunAgentArgs,
+): Promise<string> {
+  const desc = `agent "${args.agent}" in org "${args.org}"`;
+  return withTransport(serverAddress, token, async (transport, callOptions) => {
+    const query = createClient(AgentQueryController, transport);
+    let agentId: string;
+    try {
+      const agent = await query.getByReference(
+        { org: args.org, kind: ApiResourceKind.agent, slug: args.agent },
+        callOptions,
+      );
+      agentId = agent.metadata?.id ?? "";
+    } catch (err) {
+      throw rpcError(err, desc);
+    }
+
+    const execution = createMessage(AgentExecutionSchema, {
+      apiVersion: API_VERSION,
+      kind: "AgentExecution",
+      metadata: createMessage(ApiResourceMetadataSchema, { name: executionName(), org: args.org }),
+      spec: createMessage(AgentExecutionSpecSchema, {
+        // Empty message means "just run" — the CLI applies the same default.
+        message: args.message === "" ? "execute" : args.message,
+        runtimeEnv: toExecutionValues(args.runtimeEnv),
+        sessionId: args.sessionId ?? "",
+        agentId,
+      }),
+    });
+
+    const command = createClient(AgentExecutionCommandController, transport);
+    try {
+      const created = await command.create(execution, callOptions);
+      return toProtoJson(AgentExecutionSchema, created);
+    } catch (err) {
+      throw rpcError(err, `execution of ${desc}`);
+    }
+  });
+}
+
+/**
+ * Convert the tool's plain string map to the proto ExecutionValue map. Values
+ * arriving through an MCP tool call have already passed through the model's
+ * context, so they are never secrets by definition — secrets reach executions
+ * through Environments, not through this tool.
+ */
+export function toExecutionValues(
+  env: Record<string, string> | undefined,
+): Record<string, ExecutionValue> {
+  const out: Record<string, ExecutionValue> = {};
+  for (const [key, value] of Object.entries(env ?? {})) {
+    out[key] = createMessage(ExecutionValueSchema, { value, isSecret: false });
+  }
+  return out;
+}
+
+/**
+ * Unique-enough placeholder name; the backend owns final identity. Mirrors the
+ * CLI's executionName (Go's fmt.Sprintf("execution-%d", UnixMicro())).
+ */
+export function executionName(): string {
+  return `execution-${Date.now() * 1000}`;
+}

package/src/domains/agentexecutions/tools.ts

@@ -0,0 +1,139 @@
+// MCP tools for the AgentExecution domain: start a run, poll it, and answer
+// its approval requests. Together with cancel_execution (executions domain)
+// these close the agent iteration loop: author with apply_agent, run with
+// run_agent, observe with get_agent_execution, steer with
+// submit_agent_execution_approval.
+//
+// The execution model is asynchronous by design: run_agent returns as soon as
+// the backend accepts the execution; progress is observed by polling. Agent
+// executions have no event-log RPC, so get_agent_execution IS the poll loop —
+// which is why it defaults to the compact view (see fetch.ts).
+
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+
+import { resolveToken, type BackendTarget } from "../client.js";
+import { textOrError } from "../toolresult.js";
+import { submitAgentApproval } from "./approve.js";
+import { DEFAULT_MESSAGE_LIMIT, fetchAgentExecution } from "./fetch.js";
+import { runAgent } from "./run.js";
+
+/** Register every AgentExecution-domain tool; returns the registered tool names. */
+export function registerAgentExecutionTools(server: McpServer, target: BackendTarget): string[] {
+  server.registerTool(
+    "run_agent",
+    {
+      description:
+        "Start an agent execution (asynchronous). Returns immediately with the created execution " +
+        "(aex_* ID) while the run continues in the background — poll get_agent_execution to observe " +
+        "progress, pending approvals, and the final result. Omit session_id to start a fresh " +
+        "conversation; pass one to send a follow-up message into an existing session.",
+      inputSchema: {
+        org: z.string().describe("Organization slug that owns the agent (e.g. stigmer)."),
+        agent: z
+          .string()
+          .describe("Agent slug — the unique identifier within the org (e.g. code-reviewer)."),
+        message: z.string().describe("The instruction or message for the agent to act on."),
+        session_id: z
+          .string()
+          .optional()
+          .describe(
+            "Existing session ID to continue a conversation (from a previous execution's " +
+              "spec.session_id). Omit to start a new session.",
+          ),
+        runtime_env: z
+          .record(z.string())
+          .optional()
+          .describe(
+            "Non-secret runtime environment values (name → value) injected into the run. " +
+              "Secrets must come from Environments attached to the agent, never through this tool.",
+          ),
+      },
+    },
+    (args, extra) =>
+      textOrError(() =>
+        runAgent(target.serverAddress, resolveToken(extra, target.apiKey), {
+          org: args.org,
+          agent: args.agent,
+          message: args.message,
+          sessionId: args.session_id,
+          runtimeEnv: args.runtime_env,
+        }),
+      ),
+  );
+
+  server.registerTool(
+    "get_agent_execution",
+    {
+      description:
+        "Get an agent execution's status: phase, messages, pending approvals, errors, timing. " +
+        "Agent executions have no event log — poll this tool to track a run started with run_agent " +
+        "(terminal phases: completed, failed, cancelled, terminated). The default compact view " +
+        "returns the last few messages and omits bulky bookkeeping fields (resolved context, " +
+        "approval ledger, sub-agent transcripts); total_messages tells you when the tail is a " +
+        "window. Use view=full for the complete record.",
+      inputSchema: {
+        execution_id: z.string().describe("Agent execution ID (aex_* format)."),
+        view: z
+          .enum(["compact", "full"])
+          .optional()
+          .describe("Response shape: compact (default, bounded message tail) or full protojson."),
+        message_limit: z
+          .number()
+          .int()
+          .min(1)
+          .optional()
+          .describe(`Compact view only: number of trailing messages to return (default ${DEFAULT_MESSAGE_LIMIT}).`),
+      },
+    },
+    (args, extra) =>
+      textOrError(() =>
+        fetchAgentExecution(
+          target.serverAddress,
+          resolveToken(extra, target.apiKey),
+          args.execution_id,
+          args.view ?? "compact",
+          args.message_limit ?? DEFAULT_MESSAGE_LIMIT,
+        ),
+      ),
+  );
+
+  server.registerTool(
+    "submit_agent_execution_approval",
+    {
+      description:
+        "Approve, skip, or reject a tool call an agent execution is waiting on (phase " +
+        "waiting-for-approval). Find pending requests in get_agent_execution's " +
+        "status.pending_approvals — tool_call_id must match exactly. reject denies the single " +
+        "tool call and feeds your comment back to the agent, which then continues; to stop the " +
+        "whole run use cancel_execution instead.",
+      inputSchema: {
+        execution_id: z.string().describe("Agent execution ID (aex_* format)."),
+        tool_call_id: z
+          .string()
+          .describe("Tool call awaiting the decision (status.pending_approvals[].tool_call_id)."),
+        action: z
+          .enum(["approve", "skip", "reject"])
+          .describe(
+            "approve: execute the tool. skip: don't execute, agent proceeds without it. " +
+              "reject: don't execute, agent is told why (see comment) and adapts.",
+          ),
+        comment: z
+          .string()
+          .optional()
+          .describe("Reason for the decision; on reject it is fed back to the agent."),
+      },
+    },
+    (args, extra) =>
+      textOrError(() =>
+        submitAgentApproval(target.serverAddress, resolveToken(extra, target.apiKey), {
+          executionId: args.execution_id,
+          toolCallId: args.tool_call_id,
+          action: args.action,
+          comment: args.comment,
+        }),
+      ),
+  );
+
+  return ["run_agent", "get_agent_execution", "submit_agent_execution_approval"];
+}

package/src/domains/apply.integration.test.ts

@@ -1,9 +1,11 @@
 // In-process integration test for the apply tools. Drives apply_agent,
-// apply_mcp_server, and apply_workflow through the full MCP boundary and asserts
-// the codegen projection (src/gen/*) reconstitutes the proto correctly: metadata
-// hoist + slug generation, enum-string conversion, ApiResourceReference kind
-// injection, the stdio/http oneof, and the recursive workflow task_config
-// expansion (http_call leaf, fork/for_each nesting).
+// apply_mcp_server, apply_workflow, apply_environment, and apply_datastore
+// through the full MCP boundary and asserts the codegen projection (src/gen/*)
+// reconstitutes the proto correctly: metadata hoist + slug generation,
+// enum-string conversion (including repeated enums — datastore grant verbs),
+// ApiResourceReference kind injection, the stdio/http oneof, the environment
+// data map with secret flags, and the recursive workflow task_config expansion
+// (http_call leaf, fork/for_each nesting).
 
 import type { ConnectRouter } from "@connectrpc/connect";
 import { connectNodeAdapter } from "@connectrpc/connect-node";
@@ -18,6 +20,11 @@ import { Client } from "@modelcontextprotocol/sdk/client/index.js";
 import { InMemoryTransport } from "@modelcontextprotocol/sdk/inMemory.js";
 import type { Agent } from "@stigmer/protos/ai/stigmer/agentic/agent/v1/api_pb";
 import { AgentCommandController } from "@stigmer/protos/ai/stigmer/agentic/agent/v1/command_pb";
+import type { Datastore } from "@stigmer/protos/ai/stigmer/agentic/datastore/v1/api_pb";
+import { DatastoreCommandController } from "@stigmer/protos/ai/stigmer/agentic/datastore/v1/command_pb";
+import { DatastoreVerb, FieldType } from "@stigmer/protos/ai/stigmer/agentic/datastore/v1/spec_pb";
+import type { Environment } from "@stigmer/protos/ai/stigmer/agentic/environment/v1/api_pb";
+import { EnvironmentCommandController } from "@stigmer/protos/ai/stigmer/agentic/environment/v1/command_pb";
 import type { McpServer as McpServerProto } from "@stigmer/protos/ai/stigmer/agentic/mcpserver/v1/api_pb";
 import { McpServerCommandController } from "@stigmer/protos/ai/stigmer/agentic/mcpserver/v1/command_pb";
 import type { Workflow } from "@stigmer/protos/ai/stigmer/agentic/workflow/v1/api_pb";
@@ -37,6 +44,8 @@ let client: Client;
 let appliedAgent: Agent | undefined;
 let appliedMcpServer: McpServerProto | undefined;
 let appliedWorkflow: Workflow | undefined;
+let appliedEnvironment: Environment | undefined;
+let appliedDatastore: Datastore | undefined;
 const openSessions = new Set<ServerHttp2Session>();
 
 interface ToolResult {
@@ -68,6 +77,18 @@ beforeAll(async () => {
         return req;
       },
     });
+    router.service(EnvironmentCommandController, {
+      apply: (req) => {
+        appliedEnvironment = req;
+        return req;
+      },
+    });
+    router.service(DatastoreCommandController, {
+      apply: (req) => {
+        appliedDatastore = req;
+        return req;
+      },
+    });
   };
   backend = createHttp2Server(connectNodeAdapter({ routes }));
   backend.on("session", (session) => {
@@ -93,7 +114,13 @@ describe("apply tools integration", () => {
   it("advertises every apply tool", async () => {
     const { tools } = await client.listTools();
     expect(tools.map((t) => t.name)).toEqual(
-      expect.arrayContaining(["apply_agent", "apply_mcp_server", "apply_workflow"]),
+      expect.arrayContaining([
+        "apply_agent",
+        "apply_mcp_server",
+        "apply_workflow",
+        "apply_environment",
+        "apply_datastore",
+      ]),
     );
   });
 
@@ -217,4 +244,53 @@ describe("apply tools integration", () => {
     expect(forCfg.each).toBe("item");
     expect(forCfg.do).toHaveLength(1);
   });
+
+  it("apply_environment rebuilds the data map with secret flags", async () => {
+    const result = await callTool("apply_environment", {
+      name: "GitHub Creds",
+      org: "acme",
+      data: {
+        API_KEY: { value: "sk-real-value", is_secret: true, description: "GitHub PAT" },
+        REGION: { value: "us-east-1" },
+      },
+    });
+    expect(result.isError).toBeFalsy();
+
+    const env = appliedEnvironment;
+    expect(env?.apiVersion).toBe("agentic.stigmer.ai/v1");
+    expect(env?.kind).toBe("Environment");
+    expect(env?.metadata?.slug).toBe("github-creds"); // auto-generated from name
+    expect(env?.spec?.data?.API_KEY).toMatchObject({
+      value: "sk-real-value",
+      isSecret: true,
+      description: "GitHub PAT",
+    });
+    expect(env?.spec?.data?.REGION?.isSecret).toBe(false);
+  });
+
+  it("apply_datastore maps field types and repeated grant verbs to enums", async () => {
+    const result = await callTool("apply_datastore", {
+      name: "Bookings",
+      org: "acme",
+      collections: [
+        {
+          name: "appointments",
+          fields: [{ name: "patient", type: "string", required: true }],
+          grants: [{ role: "assistant", verbs: ["read", "insert"], scope: "own" }],
+        },
+      ],
+    });
+    expect(result.isError).toBeFalsy();
+
+    const ds = appliedDatastore;
+    expect(ds?.kind).toBe("Datastore");
+    expect(ds?.metadata?.slug).toBe("bookings");
+
+    const collection = ds?.spec?.collections?.[0];
+    expect(collection?.fields?.[0]?.type).toBe(FieldType.string);
+
+    // Repeated enum: verb strings map to DatastoreVerb values, not raw strings.
+    const grant = collection?.grants?.[0];
+    expect(grant?.verbs).toEqual([DatastoreVerb.read, DatastoreVerb.insert]);
+  });
 });

package/src/domains/datastores/apply.ts

@@ -0,0 +1,33 @@
+// Datastore apply path: create-or-update via DatastoreCommandController.apply.
+// The flat MCP input is projected into a fully-formed Datastore proto by the
+// generated datastoreInputToProto bridge (codegen, src/gen/datastore.ts).
+//
+// The manifest is authoritative for structure, never for data: schema changes
+// sync on apply (the server enforces its additive-plus change matrix), and
+// records enter exclusively through the record tools.
+
+import { DatastoreSchema } from "@stigmer/protos/ai/stigmer/agentic/datastore/v1/api_pb";
+import { DatastoreCommandController } from "@stigmer/protos/ai/stigmer/agentic/datastore/v1/command_pb";
+
+import { datastoreInputToProto, type DatastoreInput } from "../../gen/datastore.js";
+import { withClient } from "../client.js";
+import { toProtoJson } from "../marshal.js";
+import { rpcError } from "../rpcerr.js";
+
+/** Create or update a datastore, returning the persisted resource as protojson. */
+export async function applyDatastore(
+  serverAddress: string,
+  token: string,
+  input: DatastoreInput,
+): Promise<string> {
+  const datastore = datastoreInputToProto(input);
+  const desc = `datastore "${datastore.metadata?.slug ?? ""}" in org "${datastore.metadata?.org ?? ""}"`;
+  return withClient(DatastoreCommandController, serverAddress, token, async (client, callOptions) => {
+    try {
+      const result = await client.apply(datastore, callOptions);
+      return toProtoJson(DatastoreSchema, result);
+    } catch (err) {
+      throw rpcError(err, desc);
+    }
+  });
+}

package/src/domains/datastores/delete.ts

@@ -0,0 +1,47 @@
+// Datastore delete path: resolve org/slug → id via the Query controller, then
+// delete via the Command controller, both over a single shared transport. Like
+// McpServer, the command controller takes ApiResourceDeleteInput{resource_id}.
+//
+// This is the only path that destroys collections — record tools can delete
+// individual records but never structure.
+
+import { createClient } from "@connectrpc/connect";
+import { DatastoreSchema } from "@stigmer/protos/ai/stigmer/agentic/datastore/v1/api_pb";
+import { DatastoreCommandController } from "@stigmer/protos/ai/stigmer/agentic/datastore/v1/command_pb";
+import { DatastoreQueryController } from "@stigmer/protos/ai/stigmer/agentic/datastore/v1/query_pb";
+import { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
+
+import { withTransport } from "../client.js";
+import { toProtoJson } from "../marshal.js";
+import { rpcError } from "../rpcerr.js";
+
+/** Delete a datastore by org and slug, returning the deleted resource as protojson. */
+export async function deleteDatastore(
+  serverAddress: string,
+  token: string,
+  org: string,
+  slug: string,
+): Promise<string> {
+  const desc = `datastore "${slug}" in org "${org}"`;
+  return withTransport(serverAddress, token, async (transport, callOptions) => {
+    const query = createClient(DatastoreQueryController, transport);
+    let id: string;
+    try {
+      const datastore = await query.getByReference(
+        { org, kind: ApiResourceKind.datastore, slug },
+        callOptions,
+      );
+      id = datastore.metadata?.id ?? "";
+    } catch (err) {
+      throw rpcError(err, desc);
+    }
+
+    const command = createClient(DatastoreCommandController, transport);
+    try {
+      const deleted = await command.delete({ resourceId: id }, callOptions);
+      return toProtoJson(DatastoreSchema, deleted);
+    } catch (err) {
+      throw rpcError(err, desc);
+    }
+  });
+}

package/src/domains/datastores/fetch.ts

@@ -0,0 +1,32 @@
+// Datastore-definition read path: the single RPC both the get_datastore tool
+// and the datastore resource template delegate to. This is the *structure*
+// surface (collections, constraints, grants); living records are served by the
+// record tools (records/), whose agent-facing summary is describe_datastore.
+
+import { DatastoreSchema } from "@stigmer/protos/ai/stigmer/agentic/datastore/v1/api_pb";
+import { DatastoreQueryController } from "@stigmer/protos/ai/stigmer/agentic/datastore/v1/query_pb";
+import { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
+
+import { withClient } from "../client.js";
+import { toProtoJson } from "../marshal.js";
+import { rpcError } from "../rpcerr.js";
+
+/** Retrieve a datastore by org and slug, returning its protojson representation. */
+export async function fetchDatastore(
+  serverAddress: string,
+  token: string,
+  org: string,
+  slug: string,
+): Promise<string> {
+  return withClient(DatastoreQueryController, serverAddress, token, async (client, callOptions) => {
+    try {
+      const datastore = await client.getByReference(
+        { org, kind: ApiResourceKind.datastore, slug },
+        callOptions,
+      );
+      return toProtoJson(DatastoreSchema, datastore);
+    } catch (err) {
+      throw rpcError(err, `datastore "${slug}" in org "${org}"`);
+    }
+  });
+}