@stigmer/mcp-server 3.2.3 → 3.4.0

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}"`);
+    }
+  });
+}

package/src/domains/datastores/resources.ts

@@ -0,0 +1,21 @@
+// Datastore resource template (stigmer://datastores/{org}/{slug}).
+
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+
+import type { BackendTarget } from "../client.js";
+import { registerResource } from "../resourcehandler.js";
+import { fetchDatastore } from "./fetch.js";
+
+/** Register the datastore resource template; returns the registered resource names. */
+export function registerDatastoreResources(server: McpServer, target: BackendTarget): string[] {
+  registerResource(server, target, {
+    name: "stigmer_datastore",
+    title: "Stigmer Datastore",
+    description:
+      "Full definition of a Stigmer datastore (collections, constraints, grants), " +
+      "identified by organization and slug.",
+    template: "stigmer://datastores/{org}/{slug}",
+    fetch: fetchDatastore,
+  });
+  return ["stigmer_datastore"];
+}

package/src/domains/datastores/tools.ts

@@ -0,0 +1,76 @@
+// MCP tools for the Datastore *definition* domain — the structure surface
+// (collections, fields, constraints, roles, grants). The record tools
+// (records/tools.ts) operate on the living data inside these structures;
+// before this domain existed, an assistant could insert records into a
+// datastore it had no way to create.
+
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+
+import { DatastoreInputShape } from "../../gen/datastore.js";
+import { resolveToken, type BackendTarget } from "../client.js";
+import { textOrError } from "../toolresult.js";
+import { applyDatastore } from "./apply.js";
+import { deleteDatastore } from "./delete.js";
+import { fetchDatastore } from "./fetch.js";
+
+/** Register every Datastore-domain tool; returns the registered tool names. */
+export function registerDatastoreTools(server: McpServer, target: BackendTarget): string[] {
+  server.registerTool(
+    "get_datastore",
+    {
+      description:
+        "Get the full definition of a Stigmer datastore by its org and slug: collections, field " +
+        "declarations, constraints, roles, and grants. For the record-facing view of the same " +
+        "structure (allowed verbs, readable fields), use describe_datastore; for the data " +
+        "itself, use the record tools.",
+      inputSchema: {
+        org: z.string().describe("Organization slug that owns the datastore (e.g. stigmer)."),
+        slug: z
+          .string()
+          .describe("Datastore slug — the unique identifier within the org (e.g. clinic-bookings)."),
+      },
+    },
+    (args, extra) =>
+      textOrError(() =>
+        fetchDatastore(target.serverAddress, resolveToken(extra, target.apiKey), args.org, args.slug),
+      ),
+  );
+
+  server.registerTool(
+    "apply_datastore",
+    {
+      description:
+        "Create or update a Stigmer datastore definition (idempotent). The manifest is " +
+        "authoritative for structure only — schema changes sync on apply (the server enforces " +
+        "its additive-plus change rules), and records are never touched; use the record tools " +
+        "to manage data.",
+      inputSchema: DatastoreInputShape,
+    },
+    (args, extra) =>
+      textOrError(() =>
+        applyDatastore(target.serverAddress, resolveToken(extra, target.apiKey), args),
+      ),
+  );
+
+  server.registerTool(
+    "delete_datastore",
+    {
+      description:
+        "Delete a Stigmer datastore by its org and slug, destroying its collections and all " +
+        "records in them. This is irreversible. Returns the deleted datastore definition.",
+      inputSchema: {
+        org: z.string().describe("Organization slug that owns the datastore (e.g. stigmer)."),
+        slug: z
+          .string()
+          .describe("Datastore slug — the unique identifier within the org (e.g. clinic-bookings)."),
+      },
+    },
+    (args, extra) =>
+      textOrError(() =>
+        deleteDatastore(target.serverAddress, resolveToken(extra, target.apiKey), args.org, args.slug),
+      ),
+  );
+
+  return ["get_datastore", "apply_datastore", "delete_datastore"];
+}

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

@@ -1,7 +1,8 @@
 // In-process integration test for the delete tools. Verifies the two-step
 // resolve→delete flow forwards the resolved id into the correct per-domain
-// delete-input shape: typed {value} for agent/skill/workflow, and the
-// ApiResourceDeleteInput {resource_id} outlier for mcp_server.
+// delete-input shape: typed {value} for agent/skill/workflow, and
+// ApiResourceDeleteInput {resource_id} for mcp_server, environment, and
+// datastore.
 
 import { create, toJson } from "@bufbuild/protobuf";
 import type { ConnectRouter } from "@connectrpc/connect";
@@ -18,6 +19,12 @@ import { InMemoryTransport } from "@modelcontextprotocol/sdk/inMemory.js";
 import { AgentSchema } from "@stigmer/protos/ai/stigmer/agentic/agent/v1/api_pb";
 import { AgentCommandController } from "@stigmer/protos/ai/stigmer/agentic/agent/v1/command_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 { DatastoreCommandController } from "@stigmer/protos/ai/stigmer/agentic/datastore/v1/command_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 { EnvironmentCommandController } from "@stigmer/protos/ai/stigmer/agentic/environment/v1/command_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 { McpServerCommandController } from "@stigmer/protos/ai/stigmer/agentic/mcpserver/v1/command_pb";
 import { McpServerQueryController } from "@stigmer/protos/ai/stigmer/agentic/mcpserver/v1/query_pb";
@@ -38,11 +45,23 @@ const resolvedMcpServer = create(McpServerSchema, {
   kind: "mcp_server",
   metadata: { name: "GitHub", slug: "github", org: "acme", id: "mcp-456" },
 });
+const resolvedEnvironment = create(EnvironmentSchema, {
+  apiVersion: "v1",
+  kind: "environment",
+  metadata: { name: "GitHub Creds", slug: "github-creds", org: "acme", id: "env-789" },
+});
+const resolvedDatastore = create(DatastoreSchema, {
+  apiVersion: "v1",
+  kind: "datastore",
+  metadata: { name: "Bookings", slug: "bookings", org: "acme", id: "dst-012" },
+});
 
 let backend: Http2Server;
 let client: Client;
 let deletedAgentId: string | undefined;
 let deletedMcpResourceId: string | undefined;
+let deletedEnvironmentResourceId: string | undefined;
+let deletedDatastoreResourceId: string | undefined;
 const openSessions = new Set<ServerHttp2Session>();
 
 interface ToolResult {
@@ -70,6 +89,20 @@ beforeAll(async () => {
         return resolvedMcpServer;
       },
     });
+    router.service(EnvironmentQueryController, { getByReference: () => resolvedEnvironment });
+    router.service(EnvironmentCommandController, {
+      delete: (req) => {
+        deletedEnvironmentResourceId = req.resourceId;
+        return resolvedEnvironment;
+      },
+    });
+    router.service(DatastoreQueryController, { getByReference: () => resolvedDatastore });
+    router.service(DatastoreCommandController, {
+      delete: (req) => {
+        deletedDatastoreResourceId = req.resourceId;
+        return resolvedDatastore;
+      },
+    });
   };
   backend = createHttp2Server(connectNodeAdapter({ routes }));
   backend.on("session", (session) => {
@@ -100,6 +133,8 @@ describe("delete tools integration", () => {
         "delete_skill",
         "delete_workflow",
         "delete_mcp_server",
+        "delete_environment",
+        "delete_datastore",
       ]),
     );
   });
@@ -121,4 +156,16 @@ describe("delete tools integration", () => {
       toJson(McpServerSchema, resolvedMcpServer, { useProtoFieldName: true }),
     );
   });
+
+  it("delete_environment resolves the id then deletes via ApiResourceDeleteInput", async () => {
+    const result = await callTool("delete_environment", { org: "acme", slug: "github-creds" });
+    expect(result.isError).toBeFalsy();
+    expect(deletedEnvironmentResourceId).toBe("env-789");
+  });
+
+  it("delete_datastore resolves the id then deletes via ApiResourceDeleteInput", async () => {
+    const result = await callTool("delete_datastore", { org: "acme", slug: "bookings" });
+    expect(result.isError).toBeFalsy();
+    expect(deletedDatastoreResourceId).toBe("dst-012");
+  });
 });

package/src/domains/environments/apply.ts

@@ -0,0 +1,40 @@
+// Environment apply path: create-or-update via EnvironmentCommandController.apply.
+// The flat MCP input is projected into a fully-formed Environment proto by the
+// generated environmentInputToProto bridge (codegen, src/gen/environment.ts).
+//
+// Secret round-trip contract: a get → edit → apply loop is safe even when
+// secrets are present. The server redacts secret values to ***REDACTED*** on
+// read, and its update pipeline treats an echoed marker as "preserve the
+// existing secret" — so callers only ever send real secret values when
+// setting or rotating them.
+
+import { EnvironmentSchema } from "@stigmer/protos/ai/stigmer/agentic/environment/v1/api_pb";
+import { EnvironmentCommandController } from "@stigmer/protos/ai/stigmer/agentic/environment/v1/command_pb";
+
+import { environmentInputToProto, type EnvironmentInput } from "../../gen/environment.js";
+import { withClient } from "../client.js";
+import { toProtoJson } from "../marshal.js";
+import { rpcError } from "../rpcerr.js";
+
+/** Create or update an environment, returning the persisted resource as protojson. */
+export async function applyEnvironment(
+  serverAddress: string,
+  token: string,
+  input: EnvironmentInput,
+): Promise<string> {
+  const environment = environmentInputToProto(input);
+  const desc = `environment "${environment.metadata?.slug ?? ""}" in org "${environment.metadata?.org ?? ""}"`;
+  return withClient(
+    EnvironmentCommandController,
+    serverAddress,
+    token,
+    async (client, callOptions) => {
+      try {
+        const result = await client.apply(environment, callOptions);
+        return toProtoJson(EnvironmentSchema, result);
+      } catch (err) {
+        throw rpcError(err, desc);
+      }
+    },
+  );
+}

package/src/domains/environments/delete.ts

@@ -0,0 +1,45 @@
+// Environment 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 the generic
+// ApiResourceDeleteInput{resource_id}.
+
+import { createClient } from "@connectrpc/connect";
+import { EnvironmentSchema } from "@stigmer/protos/ai/stigmer/agentic/environment/v1/api_pb";
+import { EnvironmentCommandController } from "@stigmer/protos/ai/stigmer/agentic/environment/v1/command_pb";
+import { EnvironmentQueryController } from "@stigmer/protos/ai/stigmer/agentic/environment/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 an environment by org and slug, returning the deleted resource as protojson. */
+export async function deleteEnvironment(
+  serverAddress: string,
+  token: string,
+  org: string,
+  slug: string,
+): Promise<string> {
+  const desc = `environment "${slug}" in org "${org}"`;
+  return withTransport(serverAddress, token, async (transport, callOptions) => {
+    const query = createClient(EnvironmentQueryController, transport);
+    let id: string;
+    try {
+      const environment = await query.getByReference(
+        { org, kind: ApiResourceKind.environment, slug },
+        callOptions,
+      );
+      id = environment.metadata?.id ?? "";
+    } catch (err) {
+      throw rpcError(err, desc);
+    }
+
+    const command = createClient(EnvironmentCommandController, transport);
+    try {
+      const deleted = await command.delete({ resourceId: id }, callOptions);
+      return toProtoJson(EnvironmentSchema, deleted);
+    } catch (err) {
+      throw rpcError(err, desc);
+    }
+  });
+}