@stigmer/mcp-server 3.3.0 → 3.4.0

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

@@ -0,0 +1,376 @@
+// In-process integration test for the execution-loop tools: run_agent,
+// run_workflow, get_agent_execution, the two approval tools,
+// list_pending_approvals, and cancel_execution.
+//
+// Same harness as reads.integration.test.ts: a real Connect backend serving
+// stubbed controllers, the MCP server driven through an in-memory client. The
+// stubs capture requests so the tests assert the exact protos the tools send
+// (slug→ID resolution, runtime-env conversion, approval enum mapping) and
+// script execution state (running vs terminal, long message histories) to
+// exercise the compact projection and the cancel short-circuit.
+
+import { create, toJson } from "@bufbuild/protobuf";
+import type { ConnectRouter } from "@connectrpc/connect";
+import { connectNodeAdapter } from "@connectrpc/connect-node";
+import {
+  createServer as createHttp2Server,
+  type Http2Server,
+  type ServerHttp2Session,
+} from "node:http2";
+import type { AddressInfo } from "node:net";
+
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { InMemoryTransport } from "@modelcontextprotocol/sdk/inMemory.js";
+import { AgentSchema } from "@stigmer/protos/ai/stigmer/agentic/agent/v1/api_pb";
+import { AgentQueryController } from "@stigmer/protos/ai/stigmer/agentic/agent/v1/query_pb";
+import {
+  AgentExecutionSchema,
+  type AgentExecution,
+} from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/api_pb";
+import { AgentExecutionCommandController } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/command_pb";
+import {
+  ApprovalAction,
+  ExecutionPhase,
+} from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+import { AgentExecutionQueryController } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/query_pb";
+import type { SubmitApprovalInput } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/io_pb";
+import { WorkflowSchema } from "@stigmer/protos/ai/stigmer/agentic/workflow/v1/api_pb";
+import { WorkflowQueryController } from "@stigmer/protos/ai/stigmer/agentic/workflow/v1/query_pb";
+import {
+  WorkflowExecutionSchema,
+  type WorkflowExecution,
+} from "@stigmer/protos/ai/stigmer/agentic/workflowexecution/v1/api_pb";
+import { WorkflowExecutionCommandController } from "@stigmer/protos/ai/stigmer/agentic/workflowexecution/v1/command_pb";
+import { ExecutionPhase as WorkflowExecutionPhase } from "@stigmer/protos/ai/stigmer/agentic/workflowexecution/v1/enum_pb";
+import {
+  PendingApprovalsListSchema,
+  type ListPendingApprovalsRequest,
+  type SubmitWorkflowTaskApprovalInput,
+} from "@stigmer/protos/ai/stigmer/agentic/workflowexecution/v1/io_pb";
+import { WorkflowExecutionQueryController } from "@stigmer/protos/ai/stigmer/agentic/workflowexecution/v1/query_pb";
+import { afterAll, beforeAll, beforeEach, describe, expect, it } from "vitest";
+
+import { configureLogger } from "../logger";
+import { createServer } from "../server";
+
+configureLogger({ level: "error", format: "text" });
+
+const knownAgent = create(AgentSchema, {
+  apiVersion: "v1",
+  kind: "agent",
+  metadata: { name: "Code Reviewer", slug: "code-reviewer", org: "acme", id: "agt_1" },
+});
+
+const knownWorkflow = create(WorkflowSchema, {
+  apiVersion: "v1",
+  kind: "workflow",
+  metadata: { name: "Release", slug: "release", org: "acme", id: "wkf_1" },
+});
+
+/** An execution with a scriptable phase and an 8-message history. */
+function agentExecutionFixture(phase: ExecutionPhase): AgentExecution {
+  return create(AgentExecutionSchema, {
+    apiVersion: "v1",
+    kind: "AgentExecution",
+    metadata: { name: "run", org: "acme", id: "aex_1" },
+    spec: { agentId: "agt_1", sessionId: "ses_1", message: "review this" },
+    status: {
+      phase,
+      messages: Array.from({ length: 8 }, (_, i) => ({ content: `msg-${i}` })),
+      // Bulk fields the compact view must prune.
+      subAgentExecutions: [{ name: "researcher", input: "dig into the logs" }],
+    },
+  });
+}
+
+function workflowExecutionFixture(phase: WorkflowExecutionPhase): WorkflowExecution {
+  return create(WorkflowExecutionSchema, {
+    apiVersion: "v1",
+    kind: "WorkflowExecution",
+    metadata: { name: "run", org: "acme", id: "wex_1" },
+    spec: { workflowId: "wkf_1" },
+    status: { phase },
+  });
+}
+
+const pendingApprovals = create(PendingApprovalsListSchema, {
+  entries: [{ executionId: "wex_1", workflowName: "Release", taskName: "sign-off" }],
+  totalCount: 1,
+});
+
+let backend: Http2Server;
+let client: Client;
+const openSessions = new Set<ServerHttp2Session>();
+
+// Captured requests / scripted state, reset per test.
+let createdAgentExecution: AgentExecution | undefined;
+let createdWorkflowExecution: WorkflowExecution | undefined;
+let agentExecutionState: AgentExecution;
+let workflowExecutionState: WorkflowExecution;
+let lastAgentApproval: SubmitApprovalInput | undefined;
+let lastWorkflowApproval: SubmitWorkflowTaskApprovalInput | undefined;
+let lastPendingApprovalsRequest: ListPendingApprovalsRequest | undefined;
+let agentCancelCalls = 0;
+let workflowCancelCalls = 0;
+
+interface ToolResult {
+  content: Array<{ type: string; text?: string }>;
+  isError?: boolean;
+}
+
+async function callTool(name: string, args: Record<string, unknown>): Promise<ToolResult> {
+  return (await client.callTool({ name, arguments: args })) as ToolResult;
+}
+
+function parseText(result: ToolResult): Record<string, unknown> {
+  return JSON.parse(result.content[0]?.text ?? "{}") as Record<string, unknown>;
+}
+
+beforeAll(async () => {
+  const routes = (router: ConnectRouter) => {
+    router.service(AgentQueryController, { getByReference: () => knownAgent });
+    router.service(AgentExecutionQueryController, {
+      get: () => agentExecutionState,
+    });
+    router.service(AgentExecutionCommandController, {
+      create: (req) => {
+        createdAgentExecution = req;
+        return agentExecutionFixture(ExecutionPhase.EXECUTION_PENDING);
+      },
+      submitApproval: (req) => {
+        lastAgentApproval = req;
+        return agentExecutionFixture(ExecutionPhase.EXECUTION_IN_PROGRESS);
+      },
+      cancel: () => {
+        agentCancelCalls++;
+        return agentExecutionFixture(ExecutionPhase.EXECUTION_CANCELLED);
+      },
+    });
+    router.service(WorkflowQueryController, { getByReference: () => knownWorkflow });
+    router.service(WorkflowExecutionQueryController, {
+      get: () => workflowExecutionState,
+      listPendingApprovals: (req) => {
+        lastPendingApprovalsRequest = req;
+        return pendingApprovals;
+      },
+    });
+    router.service(WorkflowExecutionCommandController, {
+      create: (req) => {
+        createdWorkflowExecution = req;
+        return workflowExecutionFixture(WorkflowExecutionPhase.EXECUTION_PENDING);
+      },
+      submitWorkflowTaskApproval: (req) => {
+        lastWorkflowApproval = req;
+        return workflowExecutionFixture(WorkflowExecutionPhase.EXECUTION_IN_PROGRESS);
+      },
+      cancel: () => {
+        workflowCancelCalls++;
+        return workflowExecutionFixture(WorkflowExecutionPhase.EXECUTION_CANCELLED);
+      },
+    });
+  };
+  backend = createHttp2Server(connectNodeAdapter({ routes }));
+  backend.on("session", (session) => {
+    openSessions.add(session);
+    session.on("close", () => openSessions.delete(session));
+  });
+  await new Promise<void>((resolve) => backend.listen(0, "127.0.0.1", resolve));
+  const port = (backend.address() as AddressInfo).port;
+
+  const mcp = createServer({ serverAddress: `127.0.0.1:${port}`, apiKey: "" });
+  const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair();
+  client = new Client({ name: "executions-integration", version: "test" });
+  await Promise.all([mcp.connect(serverTransport), client.connect(clientTransport)]);
+});
+
+beforeEach(() => {
+  createdAgentExecution = undefined;
+  createdWorkflowExecution = undefined;
+  agentExecutionState = agentExecutionFixture(ExecutionPhase.EXECUTION_IN_PROGRESS);
+  workflowExecutionState = workflowExecutionFixture(WorkflowExecutionPhase.EXECUTION_IN_PROGRESS);
+  lastAgentApproval = undefined;
+  lastWorkflowApproval = undefined;
+  lastPendingApprovalsRequest = undefined;
+  agentCancelCalls = 0;
+  workflowCancelCalls = 0;
+});
+
+afterAll(async () => {
+  await client?.close();
+  for (const session of openSessions) session.destroy();
+  await new Promise<void>((resolve) => backend.close(() => resolve()));
+});
+
+describe("execution tools integration", () => {
+  it("advertises the execution-loop tools", async () => {
+    const { tools } = await client.listTools();
+    expect(tools.map((t) => t.name)).toEqual(
+      expect.arrayContaining([
+        "run_agent",
+        "run_workflow",
+        "get_agent_execution",
+        "submit_agent_execution_approval",
+        "list_pending_approvals",
+        "submit_workflow_task_approval",
+        "cancel_execution",
+      ]),
+    );
+  });
+
+  it("run_agent resolves the slug and creates the execution", async () => {
+    const result = await callTool("run_agent", {
+      org: "acme",
+      agent: "code-reviewer",
+      message: "review this PR",
+      runtime_env: { REPO: "stigmer/stigmer" },
+    });
+    expect(result.isError).toBeFalsy();
+
+    expect(createdAgentExecution?.spec?.agentId).toBe("agt_1");
+    expect(createdAgentExecution?.spec?.message).toBe("review this PR");
+    expect(createdAgentExecution?.spec?.sessionId).toBe("");
+    expect(createdAgentExecution?.metadata?.org).toBe("acme");
+    // Runtime env values through MCP are never secrets.
+    expect(createdAgentExecution?.spec?.runtimeEnv?.REPO?.value).toBe("stigmer/stigmer");
+    expect(createdAgentExecution?.spec?.runtimeEnv?.REPO?.isSecret).toBe(false);
+
+    // The created execution comes back as plain protojson (its status is small).
+    const created = parseText(result);
+    expect((created.metadata as Record<string, unknown>).id).toBe("aex_1");
+  });
+
+  it("run_agent threads a session follow-up", async () => {
+    await callTool("run_agent", {
+      org: "acme",
+      agent: "code-reviewer",
+      message: "and the tests?",
+      session_id: "ses_42",
+    });
+    expect(createdAgentExecution?.spec?.sessionId).toBe("ses_42");
+  });
+
+  it("run_workflow creates the execution with the org env injected", async () => {
+    const result = await callTool("run_workflow", { org: "acme", workflow: "release" });
+    expect(result.isError).toBeFalsy();
+
+    expect(createdWorkflowExecution?.spec?.workflowId).toBe("wkf_1");
+    expect(createdWorkflowExecution?.spec?.triggerMessage).toBe("execute");
+    // The CLI-parity org injection.
+    expect(createdWorkflowExecution?.spec?.runtimeEnv?.STIGMER_ORG_ID?.value).toBe("acme");
+  });
+
+  it("run_workflow lets a caller-supplied STIGMER_ORG_ID win", async () => {
+    await callTool("run_workflow", {
+      org: "acme",
+      workflow: "release",
+      message: "ship it",
+      runtime_env: { STIGMER_ORG_ID: "other-org" },
+    });
+    expect(createdWorkflowExecution?.spec?.triggerMessage).toBe("ship it");
+    expect(createdWorkflowExecution?.spec?.runtimeEnv?.STIGMER_ORG_ID?.value).toBe("other-org");
+  });
+
+  it("get_agent_execution defaults to the compact view", async () => {
+    const result = await callTool("get_agent_execution", { execution_id: "aex_1" });
+    expect(result.isError).toBeFalsy();
+
+    const body = parseText(result);
+    expect(body.view).toBe("compact");
+    expect(body.total_messages).toBe(8);
+
+    const execution = body.execution as Record<string, unknown>;
+    const status = (execution.status ?? {}) as Record<string, unknown>;
+    const messages = status.messages as Array<Record<string, unknown>>;
+    // Default tail of 5, ending with the newest message.
+    expect(messages).toHaveLength(5);
+    expect(messages[4]?.content).toBe("msg-7");
+    // Bulk bookkeeping fields are pruned.
+    expect(status.sub_agent_executions).toBeUndefined();
+  });
+
+  it("get_agent_execution honors message_limit", async () => {
+    const body = parseText(
+      await callTool("get_agent_execution", { execution_id: "aex_1", message_limit: 2 }),
+    );
+    const status = ((body.execution as Record<string, unknown>).status ?? {}) as Record<
+      string,
+      unknown
+    >;
+    expect(status.messages as unknown[]).toHaveLength(2);
+  });
+
+  it("get_agent_execution view=full returns the backend protojson verbatim", async () => {
+    const result = await callTool("get_agent_execution", { execution_id: "aex_1", view: "full" });
+    expect(parseText(result)).toEqual(
+      toJson(AgentExecutionSchema, agentExecutionState, { useProtoFieldName: true }),
+    );
+  });
+
+  it("submit_agent_execution_approval maps the action and returns the compact view", async () => {
+    const result = await callTool("submit_agent_execution_approval", {
+      execution_id: "aex_1",
+      tool_call_id: "call_7",
+      action: "reject",
+      comment: "wrong repository",
+    });
+    expect(result.isError).toBeFalsy();
+    expect(lastAgentApproval?.agentExecutionId).toBe("aex_1");
+    expect(lastAgentApproval?.toolCallId).toBe("call_7");
+    expect(lastAgentApproval?.action).toBe(ApprovalAction.REJECT);
+    expect(lastAgentApproval?.comment).toBe("wrong repository");
+    expect(parseText(result).view).toBe("compact");
+  });
+
+  it("list_pending_approvals forwards the org and returns the inbox", async () => {
+    const result = await callTool("list_pending_approvals", { org: "acme" });
+    expect(result.isError).toBeFalsy();
+    expect(lastPendingApprovalsRequest?.org).toBe("acme");
+    expect(parseText(result)).toEqual(
+      toJson(PendingApprovalsListSchema, pendingApprovals, { useProtoFieldName: true }),
+    );
+  });
+
+  it("submit_workflow_task_approval forwards the decision and form data", async () => {
+    const result = await callTool("submit_workflow_task_approval", {
+      execution_id: "wex_1",
+      task_name: "sign-off",
+      outcome: "approve",
+      comment: "lgtm",
+      form_data: { severity: "low" },
+    });
+    expect(result.isError).toBeFalsy();
+    expect(lastWorkflowApproval?.executionId).toBe("wex_1");
+    expect(lastWorkflowApproval?.taskName).toBe("sign-off");
+    expect(lastWorkflowApproval?.outcome).toBe("approve");
+    expect(lastWorkflowApproval?.comment).toBe("lgtm");
+    expect(lastWorkflowApproval?.formData).toMatchObject({ severity: "low" });
+    // The reviewer field is server-attributed; interactive clients must not set it.
+    expect(lastWorkflowApproval?.reviewer).toBe("");
+  });
+
+  it("cancel_execution cancels a running agent execution", async () => {
+    const body = parseText(await callTool("cancel_execution", { execution_id: "aex_1" }));
+    expect(agentCancelCalls).toBe(1);
+    expect(body.already_terminal).toBe(false);
+    expect(body.view).toBe("compact");
+  });
+
+  it("cancel_execution short-circuits a terminal agent execution", async () => {
+    agentExecutionState = agentExecutionFixture(ExecutionPhase.EXECUTION_COMPLETED);
+    const body = parseText(await callTool("cancel_execution", { execution_id: "aex_1" }));
+    expect(agentCancelCalls).toBe(0);
+    expect(body.already_terminal).toBe(true);
+  });
+
+  it("cancel_execution routes workflow executions by prefix", async () => {
+    const body = parseText(await callTool("cancel_execution", { execution_id: "wex_1" }));
+    expect(workflowCancelCalls).toBe(1);
+    expect(body.already_terminal).toBe(false);
+  });
+
+  it("cancel_execution rejects an unrecognized ID format", async () => {
+    const result = await callTool("cancel_execution", { execution_id: "ses_123" });
+    expect(result.isError).toBe(true);
+    expect(result.content[0]?.text).toContain("unrecognized execution ID format");
+  });
+});

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

@@ -1,8 +1,9 @@
 // In-process integration test for the read tools (get_mcp_server, get_skill,
-// get_workflow). Stands up a real Connect backend serving the three query
-// controllers, drives the MCP server through an in-memory client, and asserts
-// each tool returns the backend's protojson verbatim (the parity contract) and
-// that get_skill forwards its optional version to the backend.
+// get_workflow, get_environment, get_datastore). Stands up a real Connect
+// backend serving the query controllers, drives the MCP server through an
+// in-memory client, and asserts each tool returns the backend's protojson
+// verbatim (the parity contract) and that get_skill forwards its optional
+// version to the backend.
 
 import { create, toJson } from "@bufbuild/protobuf";
 import type { ConnectRouter } from "@connectrpc/connect";
@@ -16,6 +17,10 @@ import type { AddressInfo } from "node:net";
 
 import { Client } from "@modelcontextprotocol/sdk/client/index.js";
 import { InMemoryTransport } from "@modelcontextprotocol/sdk/inMemory.js";
+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 { EnvironmentSchema } from "@stigmer/protos/ai/stigmer/agentic/environment/v1/api_pb";
+import { EnvironmentQueryController } from "@stigmer/protos/ai/stigmer/agentic/environment/v1/query_pb";
 import { McpServerSchema } from "@stigmer/protos/ai/stigmer/agentic/mcpserver/v1/api_pb";
 import { McpServerQueryController } from "@stigmer/protos/ai/stigmer/agentic/mcpserver/v1/query_pb";
 import { SkillSchema } from "@stigmer/protos/ai/stigmer/agentic/skill/v1/api_pb";
@@ -47,6 +52,21 @@ const knownWorkflow = create(WorkflowSchema, {
   metadata: { name: "Release", slug: "release", org: "acme", id: "wkf-1" },
 });
 
+// The backend redacts secret values before they leave the server; the tool
+// must pass that redaction through verbatim.
+const knownEnvironment = create(EnvironmentSchema, {
+  apiVersion: "v1",
+  kind: "environment",
+  metadata: { name: "GitHub Creds", slug: "github-creds", org: "acme", id: "env-1" },
+  spec: { data: { API_KEY: { value: "***REDACTED***", isSecret: true } } },
+});
+
+const knownDatastore = create(DatastoreSchema, {
+  apiVersion: "v1",
+  kind: "datastore",
+  metadata: { name: "Bookings", slug: "bookings", org: "acme", id: "dst-1" },
+});
+
 let backend: Http2Server;
 let client: Client;
 let lastSkillVersion: string | undefined;
@@ -71,6 +91,8 @@ beforeAll(async () => {
       },
     });
     router.service(WorkflowQueryController, { getByReference: () => knownWorkflow });
+    router.service(EnvironmentQueryController, { getByReference: () => knownEnvironment });
+    router.service(DatastoreQueryController, { getByReference: () => knownDatastore });
   };
   backend = createHttp2Server(connectNodeAdapter({ routes }));
   // Force keep-alive sessions closed on teardown, else backend.close() blocks.
@@ -97,7 +119,14 @@ describe("read tools integration", () => {
   it("advertises all read tools", async () => {
     const { tools } = await client.listTools();
     expect(tools.map((t) => t.name)).toEqual(
-      expect.arrayContaining(["get_agent", "get_mcp_server", "get_skill", "get_workflow"]),
+      expect.arrayContaining([
+        "get_agent",
+        "get_mcp_server",
+        "get_skill",
+        "get_workflow",
+        "get_environment",
+        "get_datastore",
+      ]),
     );
   });
 
@@ -131,4 +160,21 @@ describe("read tools integration", () => {
     await callTool("get_skill", { org: "acme", slug: "code-review", version: "stable" });
     expect(lastSkillVersion).toBe("stable");
   });
+
+  it("get_environment passes the server's secret redaction through verbatim", async () => {
+    const result = await callTool("get_environment", { org: "acme", slug: "github-creds" });
+    expect(result.isError).toBeFalsy();
+    const body = JSON.parse(result.content[0]?.text ?? "{}") as Record<string, unknown>;
+    expect(body).toEqual(toJson(EnvironmentSchema, knownEnvironment, { useProtoFieldName: true }));
+    const data = (body.spec as { data: Record<string, { value: string }> }).data;
+    expect(data.API_KEY?.value).toBe("***REDACTED***");
+  });
+
+  it("get_datastore returns the backend protojson", async () => {
+    const result = await callTool("get_datastore", { org: "acme", slug: "bookings" });
+    expect(result.isError).toBeFalsy();
+    expect(JSON.parse(result.content[0]?.text ?? "{}")).toEqual(
+      toJson(DatastoreSchema, knownDatastore, { useProtoFieldName: true }),
+    );
+  });
 });

package/src/domains/records/tools.ts

@@ -84,8 +84,10 @@ export function registerRecordTools(
       description:
         "Describe a datastore: its collections, field declarations and encodings, constraint " +
         "messages, data partitions, and the verbs you are allowed to use per collection " +
-        "(empty access means you are not allowed to touch that collection). Call this before " +
-        `the first record operation against an unfamiliar datastore. ${ENCODINGS}`,
+        "(empty access means you are not allowed to touch that collection). A read verb may " +
+        "carry readable_fields: reads then return only those fields, and only they may appear " +
+        "in filter conditions and order_by (empty readable_fields means every field). Call " +
+        `this before the first record operation against an unfamiliar datastore. ${ENCODINGS}`,
       inputSchema: {
         datastore: z.string().describe("Datastore slug (e.g. clinic)."),
         ...orgShape,
@@ -104,7 +106,9 @@ export function registerRecordTools(
       description:
         "Find records in a datastore collection with a typed filter (conditions are AND-combined). " +
         "Returns records plus total/limit/offset for paging. Results are ordered by created_at " +
-        `descending unless order_by is given. ${ENCODINGS}`,
+        "descending unless order_by is given. Records carry only the fields your grant allows " +
+        "(describe_datastore lists them as readable_fields); conditions and order_by on other " +
+        `fields are rejected. ${ENCODINGS}`,
       inputSchema: {
         datastore: z.string().describe("Datastore slug (e.g. clinic)."),
         ...orgShape,

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

@@ -1,4 +1,4 @@
-// In-process integration test for the 5 resource templates. Verifies template
+// In-process integration test for the resource templates. Verifies template
 // discovery, that each read returns the backend protojson as a single
 // application/json entry, and that the skill templates resolve latest (empty
 // version) vs a pinned version.
@@ -17,6 +17,10 @@ import { Client } from "@modelcontextprotocol/sdk/client/index.js";
 import { InMemoryTransport } from "@modelcontextprotocol/sdk/inMemory.js";
 import { AgentSchema } from "@stigmer/protos/ai/stigmer/agentic/agent/v1/api_pb";
 import { AgentQueryController } from "@stigmer/protos/ai/stigmer/agentic/agent/v1/query_pb";
+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 { EnvironmentSchema } from "@stigmer/protos/ai/stigmer/agentic/environment/v1/api_pb";
+import { EnvironmentQueryController } from "@stigmer/protos/ai/stigmer/agentic/environment/v1/query_pb";
 import { McpServerSchema } from "@stigmer/protos/ai/stigmer/agentic/mcpserver/v1/api_pb";
 import { McpServerQueryController } from "@stigmer/protos/ai/stigmer/agentic/mcpserver/v1/query_pb";
 import { SkillSchema } from "@stigmer/protos/ai/stigmer/agentic/skill/v1/api_pb";
@@ -42,6 +46,16 @@ const workflow = create(WorkflowSchema, {
   kind: "workflow",
   metadata: { slug: "w", org: "acme" },
 });
+const environment = create(EnvironmentSchema, {
+  apiVersion: "v1",
+  kind: "environment",
+  metadata: { slug: "e", org: "acme" },
+});
+const datastore = create(DatastoreSchema, {
+  apiVersion: "v1",
+  kind: "datastore",
+  metadata: { slug: "d", org: "acme" },
+});
 
 let backend: Http2Server;
 let client: Client;
@@ -63,6 +77,8 @@ beforeAll(async () => {
       },
     });
     router.service(WorkflowQueryController, { getByReference: () => workflow });
+    router.service(EnvironmentQueryController, { getByReference: () => environment });
+    router.service(DatastoreQueryController, { getByReference: () => datastore });
   };
   backend = createHttp2Server(connectNodeAdapter({ routes }));
   backend.on("session", (session) => {
@@ -85,7 +101,7 @@ afterAll(async () => {
 });
 
 describe("resource templates integration", () => {
-  it("advertises all five templates", async () => {
+  it("advertises every template", async () => {
     const { resourceTemplates } = await client.listResourceTemplates();
     expect(resourceTemplates.map((t) => t.name)).toEqual(
       expect.arrayContaining([
@@ -94,6 +110,8 @@ describe("resource templates integration", () => {
         "stigmer_skill",
         "stigmer_skill_version",
         "stigmer_workflow",
+        "stigmer_environment",
+        "stigmer_datastore",
       ]),
     );
   });
@@ -136,4 +154,22 @@ describe("resource templates integration", () => {
     await client.readResource({ uri: "stigmer://skills/acme/s/v2.0.0" });
     expect(lastSkillVersion).toBe("v2.0.0");
   });
+
+  it("reads an environment resource", async () => {
+    const result = (await client.readResource({
+      uri: "stigmer://environments/acme/e",
+    })) as ResourceResult;
+    expect(JSON.parse(result.contents[0]?.text ?? "{}")).toEqual(
+      toJson(EnvironmentSchema, environment, { useProtoFieldName: true }),
+    );
+  });
+
+  it("reads a datastore resource", async () => {
+    const result = (await client.readResource({
+      uri: "stigmer://datastores/acme/d",
+    })) as ResourceResult;
+    expect(JSON.parse(result.contents[0]?.text ?? "{}")).toEqual(
+      toJson(DatastoreSchema, datastore, { useProtoFieldName: true }),
+    );
+  });
 });

package/src/domains/resourceuri.test.ts

@@ -75,6 +75,8 @@ describe("buildResourceURI", () => {
     expect(buildResourceURI("mcp_server", "acme", "m")).toBe("stigmer://mcp-servers/acme/m");
     expect(buildResourceURI("skill", "acme", "s")).toBe("stigmer://skills/acme/s");
     expect(buildResourceURI("workflow", "acme", "w")).toBe("stigmer://workflows/acme/w");
+    expect(buildResourceURI("environment", "acme", "e")).toBe("stigmer://environments/acme/e");
+    expect(buildResourceURI("datastore", "acme", "d")).toBe("stigmer://datastores/acme/d");
   });
 
   it("round-trips with parseResourceURI", () => {
@@ -91,7 +93,14 @@ describe("buildResourceURI", () => {
     expect(buildResourceURI("agent", "acme", "")).toBe("");
   });
 
-  it("covers exactly the four templated kinds", () => {
-    expect(Object.keys(kindToAuthority).sort()).toEqual(["agent", "mcp_server", "skill", "workflow"]);
+  it("covers exactly the templated kinds", () => {
+    expect(Object.keys(kindToAuthority).sort()).toEqual([
+      "agent",
+      "datastore",
+      "environment",
+      "mcp_server",
+      "skill",
+      "workflow",
+    ]);
   });
 });

package/src/domains/resourceuri.ts

@@ -81,6 +81,8 @@ export function parseVersionedResourceURI(uri: string): VersionedResourceRef {
  */
 export const kindToAuthority: Readonly<Record<string, string>> = {
   agent: "agents",
+  datastore: "datastores",
+  environment: "environments",
   mcp_server: "mcp-servers",
   skill: "skills",
   workflow: "workflows",

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

@@ -1,5 +1,5 @@
 // In-process integration test for the search tool. Verifies resource_uri
-// enrichment for all four searchable kinds, the empty-response short-circuit,
+// enrichment for every searchable kind, the empty-response short-circuit,
 // the unknown-kind validation error, and pagination passthrough.
 
 import { create, toJson } from "@bufbuild/protobuf";
@@ -35,6 +35,12 @@ const allKindsResponse = create(SearchResponseSchema, {
     create(SearchResultSchema, { kind: ApiResourceKind.skill, org: "acme", slug: "code-review" }),
     create(SearchResultSchema, { kind: ApiResourceKind.mcp_server, org: "acme", slug: "github" }),
     create(SearchResultSchema, { kind: ApiResourceKind.workflow, org: "acme", slug: "release" }),
+    create(SearchResultSchema, {
+      kind: ApiResourceKind.environment,
+      org: "acme",
+      slug: "github-creds",
+    }),
+    create(SearchResultSchema, { kind: ApiResourceKind.datastore, org: "acme", slug: "bookings" }),
   ],
 });
 const emptyResponse = create(SearchResponseSchema, { entries: [] });
@@ -96,6 +102,8 @@ describe("search tool integration", () => {
       "stigmer://skills/acme/code-review",
       "stigmer://mcp-servers/acme/github",
       "stigmer://workflows/acme/release",
+      "stigmer://environments/acme/github-creds",
+      "stigmer://datastores/acme/bookings",
     ]);
   });
 
@@ -112,7 +120,15 @@ describe("search tool integration", () => {
     const result = await callSearch({ kinds: ["bogus"] });
     expect(result.isError).toBe(true);
     expect(result.content[0]?.text).toContain('unknown resource kind "bogus"');
-    expect(result.content[0]?.text).toContain("valid kinds: agent, skill, mcp_server, workflow");
+    expect(result.content[0]?.text).toContain(
+      "valid kinds: agent, skill, mcp_server, workflow, environment, datastore",
+    );
+  });
+
+  it("accepts the environment and datastore kinds", async () => {
+    nextResponse = emptyResponse;
+    const result = await callSearch({ kinds: ["environment", "datastore"] });
+    expect(result.isError).toBeFalsy();
   });
 
   it("forwards pagination only when requested", async () => {