@stigmer/mcp-server 3.2.3 → 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/calls.ts

@@ -0,0 +1,209 @@
+// Record-RPC invocations for the five record tools — 1:1 projections
+// of DatastoreRecordQueryController / DatastoreRecordCommandController
+// (DD-005: the tool layer adds no semantics; validation, grants,
+// scopes, constraints, and messages all live in record-RPC domain
+// logic on the control plane).
+//
+// One file for the five thin calls rather than the resource domains'
+// file-per-verb split: resource verbs each carry orchestration
+// (reference resolution, YAML parsing, two-step deletes); record calls
+// are each "build request, call, marshal" and the shared argument
+// mapping (filter/value building) is the only substance.
+
+import { create, fromJson, type JsonObject } from "@bufbuild/protobuf";
+import { ValueSchema, type Value } from "@bufbuild/protobuf/wkt";
+import {
+  DatastoreRecordCommandController,
+} from "@stigmer/protos/ai/stigmer/agentic/datastore/v1/record_command_pb";
+import {
+  DatastoreRecordQueryController,
+} from "@stigmer/protos/ai/stigmer/agentic/datastore/v1/record_query_pb";
+import {
+  DatastoreDescriptionSchema,
+  DeleteRecordRequestSchema,
+  DescribeDatastoreRequestSchema,
+  FindRecordsRequestSchema,
+  InsertRecordRequestSchema,
+  RecordConditionOp,
+  RecordConditionSchema,
+  RecordEnvelopeSchema,
+  RecordFilterSchema,
+  RecordListSchema,
+  RecordOrderBySchema,
+  RecordSortDirection,
+  UpdateRecordRequestSchema,
+  type RecordCondition,
+  type RecordFilter,
+  type RecordOrderBy,
+} from "@stigmer/protos/ai/stigmer/agentic/datastore/v1/record_io_pb";
+import { withClient } from "../client.js";
+import { toProtoJson } from "../marshal.js";
+
+/**
+ * A filter condition as the model supplies it. `op` uses the natural
+ * spelling "in" (the proto enum's `is_in` exists only because `in` is
+ * reserved in Java/Python — a substrate detail the model never sees).
+ */
+export interface ConditionArg {
+  field: string;
+  op: string;
+  value?: string | number | boolean | null;
+  values?: (string | number | boolean)[];
+}
+
+export interface FindArgs {
+  datastore: string;
+  org?: string;
+  collection: string;
+  conditions?: ConditionArg[];
+  order_by?: { field: string; direction?: string };
+  limit?: number;
+  offset?: number;
+}
+
+/** Model-facing operator spelling → proto enum. */
+const CONDITION_OPS: Readonly<Record<string, RecordConditionOp>> = {
+  eq: RecordConditionOp.eq,
+  neq: RecordConditionOp.neq,
+  gt: RecordConditionOp.gt,
+  gte: RecordConditionOp.gte,
+  lt: RecordConditionOp.lt,
+  lte: RecordConditionOp.lte,
+  in: RecordConditionOp.is_in,
+  not_in: RecordConditionOp.not_in,
+  is_null: RecordConditionOp.is_null,
+  not_null: RecordConditionOp.not_null,
+};
+
+export async function findRecords(
+  serverAddress: string,
+  token: string,
+  args: FindArgs,
+): Promise<string> {
+  const request = create(FindRecordsRequestSchema, {
+    datastore: args.datastore,
+    org: args.org ?? "",
+    collection: args.collection,
+    filter: buildFilter(args.conditions),
+    orderBy: buildOrderBy(args.order_by),
+    limit: args.limit ?? 0,
+    offset: args.offset ?? 0,
+  });
+  return withClient(DatastoreRecordQueryController, serverAddress, token, async (client, opts) =>
+    toProtoJson(RecordListSchema, await client.findRecords(request, opts)),
+  );
+}
+
+export async function insertRecord(
+  serverAddress: string,
+  token: string,
+  args: { datastore: string; org?: string; collection: string; record: Record<string, unknown> },
+): Promise<string> {
+  const request = create(InsertRecordRequestSchema, {
+    datastore: args.datastore,
+    org: args.org ?? "",
+    collection: args.collection,
+    // google.protobuf.Struct fields are plain JSON objects in
+    // protobuf-es v2 — no conversion.
+    record: args.record as JsonObject,
+  });
+  return withClient(DatastoreRecordCommandController, serverAddress, token, async (client, opts) =>
+    toProtoJson(RecordEnvelopeSchema, await client.insertRecord(request, opts)),
+  );
+}
+
+export async function updateRecord(
+  serverAddress: string,
+  token: string,
+  args: {
+    datastore: string;
+    org?: string;
+    collection: string;
+    id: string;
+    fields: Record<string, unknown>;
+  },
+): Promise<string> {
+  const request = create(UpdateRecordRequestSchema, {
+    datastore: args.datastore,
+    org: args.org ?? "",
+    collection: args.collection,
+    id: args.id,
+    fields: args.fields as JsonObject,
+  });
+  return withClient(DatastoreRecordCommandController, serverAddress, token, async (client, opts) =>
+    toProtoJson(RecordEnvelopeSchema, await client.updateRecord(request, opts)),
+  );
+}
+
+export async function deleteRecord(
+  serverAddress: string,
+  token: string,
+  args: { datastore: string; org?: string; collection: string; id: string },
+): Promise<string> {
+  const request = create(DeleteRecordRequestSchema, {
+    datastore: args.datastore,
+    org: args.org ?? "",
+    collection: args.collection,
+    id: args.id,
+  });
+  return withClient(DatastoreRecordCommandController, serverAddress, token, async (client, opts) =>
+    toProtoJson(RecordEnvelopeSchema, await client.deleteRecord(request, opts)),
+  );
+}
+
+export async function describeDatastore(
+  serverAddress: string,
+  token: string,
+  args: { datastore: string; org?: string },
+): Promise<string> {
+  const request = create(DescribeDatastoreRequestSchema, {
+    datastore: args.datastore,
+    org: args.org ?? "",
+  });
+  return withClient(DatastoreRecordQueryController, serverAddress, token, async (client, opts) =>
+    toProtoJson(DatastoreDescriptionSchema, await client.describeDatastore(request, opts)),
+  );
+}
+
+/**
+ * Build the typed AND-only filter (DD-005 SD-2). An unknown operator is
+ * left unspecified for the server to reject with its own domain
+ * message — the bridge never fabricates validation of its own.
+ */
+function buildFilter(conditions: ConditionArg[] | undefined): RecordFilter | undefined {
+  if (conditions === undefined || conditions.length === 0) {
+    return undefined;
+  }
+  return create(RecordFilterSchema, {
+    conditions: conditions.map(buildCondition),
+  });
+}
+
+function buildCondition(arg: ConditionArg): RecordCondition {
+  return create(RecordConditionSchema, {
+    field: arg.field,
+    op: CONDITION_OPS[arg.op] ?? RecordConditionOp.record_condition_op_unspecified,
+    value: arg.value !== undefined ? scalarValue(arg.value) : undefined,
+    values: (arg.values ?? []).map(scalarValue),
+  });
+}
+
+function buildOrderBy(
+  orderBy: { field: string; direction?: string } | undefined,
+): RecordOrderBy | undefined {
+  if (orderBy === undefined) {
+    return undefined;
+  }
+  return create(RecordOrderBySchema, {
+    field: orderBy.field,
+    direction: orderBy.direction === "desc"
+      ? RecordSortDirection.desc
+      : orderBy.direction === "asc"
+        ? RecordSortDirection.asc
+        : RecordSortDirection.record_sort_direction_unspecified,
+  });
+}
+
+function scalarValue(v: string | number | boolean | null): Value {
+  return fromJson(ValueSchema, v);
+}