@stigmer/mcp-server 3.3.0 → 3.4.0

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

package/src/domains/environments/fetch.ts

@@ -0,0 +1,39 @@
+// Environment read path: the single RPC both the get_environment tool and the
+// environment resource template delegate to.
+//
+// Secret handling happens entirely server-side: the response pipeline replaces
+// every is_secret value with the ***REDACTED*** sentinel before it leaves the
+// server (backend environment domain, preserve_redacted_secrets.go), so this
+// layer adds no redaction logic of its own — the server is the single
+// enforcement point.
+
+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 { 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 an environment by org and slug, returning its protojson
+ * representation (secret values arrive already redacted by the server).
+ */
+export async function fetchEnvironment(
+  serverAddress: string,
+  token: string,
+  org: string,
+  slug: string,
+): Promise<string> {
+  return withClient(EnvironmentQueryController, serverAddress, token, async (client, callOptions) => {
+    try {
+      const environment = await client.getByReference(
+        { org, kind: ApiResourceKind.environment, slug },
+        callOptions,
+      );
+      return toProtoJson(EnvironmentSchema, environment);
+    } catch (err) {
+      throw rpcError(err, `environment "${slug}" in org "${org}"`);
+    }
+  });
+}

package/src/domains/environments/resources.ts

@@ -0,0 +1,21 @@
+// Environment resource template (stigmer://environments/{org}/{slug}).
+
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+
+import type { BackendTarget } from "../client.js";
+import { registerResource } from "../resourcehandler.js";
+import { fetchEnvironment } from "./fetch.js";
+
+/** Register the environment resource template; returns the registered resource names. */
+export function registerEnvironmentResources(server: McpServer, target: BackendTarget): string[] {
+  registerResource(server, target, {
+    name: "stigmer_environment",
+    title: "Stigmer Environment",
+    description:
+      "Full definition of a Stigmer environment, identified by organization and slug. " +
+      "Secret values are redacted.",
+    template: "stigmer://environments/{org}/{slug}",
+    fetch: fetchEnvironment,
+  });
+  return ["stigmer_environment"];
+}

package/src/domains/environments/tools.ts

@@ -0,0 +1,81 @@
+// MCP tools for the Environment domain. Environments hold the configuration
+// and secrets that agents, workflows, and MCP servers resolve at runtime —
+// without these tools, an assistant authoring an agent hits a dead end the
+// moment env config is involved.
+//
+// The secret contract every description teaches: reads return secret values
+// redacted to ***REDACTED*** (server-enforced); an apply that echoes the
+// marker back preserves the existing secret, so get → edit → apply is always
+// safe. Secret values are only ever sent when setting or rotating them, and
+// they can never be read back through MCP.
+
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+
+import { EnvironmentInputShape } from "../../gen/environment.js";
+import { resolveToken, type BackendTarget } from "../client.js";
+import { textOrError } from "../toolresult.js";
+import { applyEnvironment } from "./apply.js";
+import { deleteEnvironment } from "./delete.js";
+import { fetchEnvironment } from "./fetch.js";
+
+/** Register every Environment-domain tool; returns the registered tool names. */
+export function registerEnvironmentTools(server: McpServer, target: BackendTarget): string[] {
+  server.registerTool(
+    "get_environment",
+    {
+      description:
+        "Get full details of a Stigmer environment by its org and slug, including its variable " +
+        "declarations. Secret values are redacted to ***REDACTED*** — they can never be read " +
+        "back through this tool.",
+      inputSchema: {
+        org: z.string().describe("Organization slug that owns the environment (e.g. stigmer)."),
+        slug: z
+          .string()
+          .describe("Environment slug — the unique identifier within the org (e.g. github-creds)."),
+      },
+    },
+    (args, extra) =>
+      textOrError(() =>
+        fetchEnvironment(target.serverAddress, resolveToken(extra, target.apiKey), args.org, args.slug),
+      ),
+  );
+
+  server.registerTool(
+    "apply_environment",
+    {
+      description:
+        "Create or update a Stigmer environment (idempotent). The spec is applied in full, so " +
+        "include every variable the environment should keep. When updating, secret values read " +
+        "back as ***REDACTED*** — echoing that marker preserves the existing secret, so a " +
+        "get → edit → apply round-trip never destroys secrets; send a real value only to set " +
+        "or rotate one.",
+      inputSchema: EnvironmentInputShape,
+    },
+    (args, extra) =>
+      textOrError(() =>
+        applyEnvironment(target.serverAddress, resolveToken(extra, target.apiKey), args),
+      ),
+  );
+
+  server.registerTool(
+    "delete_environment",
+    {
+      description:
+        "Delete a Stigmer environment by its org and slug. Returns the deleted environment. " +
+        "Agents and workflows referencing it will fail to resolve their variables at run time.",
+      inputSchema: {
+        org: z.string().describe("Organization slug that owns the environment (e.g. stigmer)."),
+        slug: z
+          .string()
+          .describe("Environment slug — the unique identifier within the org (e.g. github-creds)."),
+      },
+    },
+    (args, extra) =>
+      textOrError(() =>
+        deleteEnvironment(target.serverAddress, resolveToken(extra, target.apiKey), args.org, args.slug),
+      ),
+  );
+
+  return ["get_environment", "apply_environment", "delete_environment"];
+}

package/src/domains/executions/cancel.ts

@@ -0,0 +1,148 @@
+// Cross-kind execution cancellation for the cancel_execution tool.
+//
+// Executions are the one place the MCP surface routes on ID prefix rather
+// than a kind argument: agent (aex_*) and workflow (wex_*) executions live on
+// dedicated controllers but cancel with identical arguments, so one tool
+// serves both — mirroring the CLI's routing seam
+// (client-apps/cli/src/resources/execution.ts), including its cancel
+// semantics: read the execution first and short-circuit with
+// "already terminal" instead of issuing a futile cancel, so the
+// success/no-op distinction comes from authoritative state.
+
+import { createClient } from "@connectrpc/connect";
+import { 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 { ExecutionPhase as AgentExecutionPhase } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+import { AgentExecutionQueryController } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/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 { WorkflowExecutionQueryController } from "@stigmer/protos/ai/stigmer/agentic/workflowexecution/v1/query_pb";
+
+import { compactExecution, DEFAULT_MESSAGE_LIMIT } from "../agentexecutions/fetch.js";
+import { withTransport } from "../client.js";
+import { toProtoJson } from "../marshal.js";
+import { rpcError } from "../rpcerr.js";
+
+// Terminal phases per kind. The two ExecutionPhase enums live in different
+// proto packages with different numeric values (agent TERMINATED is 8,
+// workflow TERMINATED is 6), so these are deliberately separate sets.
+const TERMINAL_AGENT_PHASES: ReadonlySet<AgentExecutionPhase> = new Set([
+  AgentExecutionPhase.EXECUTION_COMPLETED,
+  AgentExecutionPhase.EXECUTION_FAILED,
+  AgentExecutionPhase.EXECUTION_CANCELLED,
+  AgentExecutionPhase.EXECUTION_TERMINATED,
+]);
+
+const TERMINAL_WORKFLOW_PHASES: ReadonlySet<WorkflowExecutionPhase> = new Set([
+  WorkflowExecutionPhase.EXECUTION_COMPLETED,
+  WorkflowExecutionPhase.EXECUTION_FAILED,
+  WorkflowExecutionPhase.EXECUTION_CANCELLED,
+  WorkflowExecutionPhase.EXECUTION_TERMINATED,
+]);
+
+/**
+ * Resolve an execution ID to its controller family by prefix. Matching is
+ * case-sensitive and accepts both separators the backend does ("_" canonical,
+ * "-" legacy), mirroring the CLI's resolveExecutionType.
+ */
+function resolveExecutionType(id: string): "agent" | "workflow" {
+  const trimmed = id.trim();
+  if (trimmed.startsWith("aex_") || trimmed.startsWith("aex-")) return "agent";
+  if (trimmed.startsWith("wex_") || trimmed.startsWith("wex-")) return "workflow";
+  throw new Error(
+    `unrecognized execution ID format: ${id}\n\n` +
+      "Expected formats:\n" +
+      "  Agent execution:    aex_<26-char-ulid>\n" +
+      "  Workflow execution: wex_<26-char-ulid>",
+  );
+}
+
+/**
+ * Cancel an execution of either kind. Returns a wrapper documenting whether a
+ * cancel was actually issued: `{"already_terminal": bool, "execution": …}`.
+ * Agent executions are returned in the compact projection (their status embeds
+ * the full message history); workflow executions as plain protojson, matching
+ * get_workflow_execution.
+ */
+export async function cancelExecution(
+  serverAddress: string,
+  token: string,
+  executionId: string,
+  reason: string,
+): Promise<string> {
+  return resolveExecutionType(executionId) === "agent"
+    ? cancelAgentExecution(serverAddress, token, executionId, reason)
+    : cancelWorkflowExecution(serverAddress, token, executionId, reason);
+}
+
+async function cancelAgentExecution(
+  serverAddress: string,
+  token: string,
+  id: string,
+  reason: string,
+): Promise<string> {
+  const desc = `agent execution "${id}"`;
+  return withTransport(serverAddress, token, async (transport, callOptions) => {
+    try {
+      const query = createClient(AgentExecutionQueryController, transport);
+      const current = await query.get({ value: id }, callOptions);
+      const phase = current.status?.phase ?? AgentExecutionPhase.EXECUTION_PHASE_UNSPECIFIED;
+      if (TERMINAL_AGENT_PHASES.has(phase)) {
+        return wrapAgent(current, true);
+      }
+      const command = createClient(AgentExecutionCommandController, transport);
+      const cancelled = await command.cancel({ id, reason }, callOptions);
+      return wrapAgent(cancelled, false);
+    } catch (err) {
+      throw rpcError(err, desc);
+    }
+  });
+}
+
+async function cancelWorkflowExecution(
+  serverAddress: string,
+  token: string,
+  id: string,
+  reason: string,
+): Promise<string> {
+  const desc = `workflow execution "${id}"`;
+  return withTransport(serverAddress, token, async (transport, callOptions) => {
+    try {
+      const query = createClient(WorkflowExecutionQueryController, transport);
+      const current = await query.get({ value: id }, callOptions);
+      const phase = current.status?.phase ?? WorkflowExecutionPhase.EXECUTION_PHASE_UNSPECIFIED;
+      if (TERMINAL_WORKFLOW_PHASES.has(phase)) {
+        return wrapWorkflow(current, true);
+      }
+      const command = createClient(WorkflowExecutionCommandController, transport);
+      const cancelled = await command.cancel({ id, reason }, callOptions);
+      return wrapWorkflow(cancelled, false);
+    } catch (err) {
+      throw rpcError(err, desc);
+    }
+  });
+}
+
+function wrapAgent(execution: AgentExecution, alreadyTerminal: boolean): string {
+  const { totalMessages, data } = compactExecution(execution, DEFAULT_MESSAGE_LIMIT);
+  return JSON.stringify(
+    { already_terminal: alreadyTerminal, view: "compact", total_messages: totalMessages, execution: data },
+    null,
+    2,
+  );
+}
+
+function wrapWorkflow(execution: WorkflowExecution, alreadyTerminal: boolean): string {
+  return JSON.stringify(
+    {
+      already_terminal: alreadyTerminal,
+      execution: JSON.parse(toProtoJson(WorkflowExecutionSchema, execution)),
+    },
+    null,
+    2,
+  );
+}

package/src/domains/executions/tools.ts

@@ -0,0 +1,45 @@
+// Cross-kind execution-control tools. Currently just cancel_execution — the
+// one control verb whose argument shape is identical for agent and workflow
+// executions, so a single ID-prefix-dispatched tool serves both (the
+// "crisp schemas over fewer tools" principle cuts the other way for
+// approvals, whose shapes are disjoint). pause/resume/terminate stay
+// CLI-only until a real MCP need shows up.
+
+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 { cancelExecution } from "./cancel.js";
+
+/** Register the cross-kind execution-control tools; returns the registered tool names. */
+export function registerExecutionControlTools(server: McpServer, target: BackendTarget): string[] {
+  server.registerTool(
+    "cancel_execution",
+    {
+      description:
+        "Gracefully cancel a running agent (aex_*) or workflow (wex_*) execution — the kind is " +
+        "inferred from the ID prefix. Cancellation is terminal: the run stops after cleanup and " +
+        "cannot be resumed. Executions already in a terminal phase are returned with " +
+        "already_terminal=true instead of an error.",
+      inputSchema: {
+        execution_id: z.string().describe("Execution ID to cancel (aex_* or wex_* format)."),
+        reason: z
+          .string()
+          .optional()
+          .describe("Human-readable reason for the cancellation, stored in the audit trail."),
+      },
+    },
+    (args, extra) =>
+      textOrError(() =>
+        cancelExecution(
+          target.serverAddress,
+          resolveToken(extra, target.apiKey),
+          args.execution_id,
+          args.reason ?? "",
+        ),
+      ),
+  );
+
+  return ["cancel_execution"];
+}