@stigmer/mcp-server 3.2.3 → 3.4.0

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 () => {

package/src/domains/search/tools.ts

@@ -24,12 +24,15 @@ import { rpcError } from "../rpcerr.js";
 import { textOrError } from "../toolresult.js";
 
 /**
- * The searchable kinds and their proto enum values. This is deliberately the
- * four searchable kinds (not every ApiResourceKind), mirroring the Go server's
- * `knownKinds` map and its validation surface.
+ * The searchable kinds and their proto enum values. Deliberately a curated
+ * subset (not every ApiResourceKind): the kinds an MCP client can also read
+ * and manage through tools. The backend's extractor registry supports more
+ * (sessions, executions, ...) — add here only alongside a tool surface.
  */
 const knownKinds: Readonly<Record<string, ApiResourceKind>> = {
   agent: ApiResourceKind.agent,
+  datastore: ApiResourceKind.datastore,
+  environment: ApiResourceKind.environment,
   skill: ApiResourceKind.skill,
   mcp_server: ApiResourceKind.mcp_server,
   workflow: ApiResourceKind.workflow,
@@ -50,14 +53,16 @@ export function registerSearchTools(server: McpServer, target: BackendTarget): s
     "search",
     {
       description:
-        "Search and list Stigmer resources (agents, skills, MCP servers, workflows). " +
-        "Set 'kinds' to filter by resource type. Set 'query' for full-text search. " +
+        "Search and list Stigmer resources (agents, skills, MCP servers, workflows, environments, " +
+        "datastores). Set 'kinds' to filter by resource type. Set 'query' for full-text search. " +
         "Set 'org' to scope to an organization. Omit 'query' to list all accessible resources.",
       inputSchema: {
         kinds: z
           .array(z.string())
           .optional()
-          .describe("Resource kinds to search. Valid: agent, skill, mcp_server, workflow. Empty searches all."),
+          .describe(
+            "Resource kinds to search. Valid: agent, skill, mcp_server, workflow, environment, datastore. Empty searches all.",
+          ),
         query: z
           .string()
           .optional()
@@ -125,7 +130,7 @@ function parseKinds(raw: string[] | undefined): ApiResourceKind[] {
     const kind = knownKinds[s];
     if (kind === undefined) {
       throw new Error(
-        `unknown resource kind "${s}"; valid kinds: agent, skill, mcp_server, workflow`,
+        `unknown resource kind "${s}"; valid kinds: agent, skill, mcp_server, workflow, environment, datastore`,
       );
     }
     return kind;

package/src/domains/skills/tools.ts

@@ -12,6 +12,7 @@ import { resolveToken, type BackendTarget } from "../client.js";
 import { textOrError } from "../toolresult.js";
 import { deleteSkill } from "./delete.js";
 import { fetchSkill } from "./fetch.js";
+import { listSkillVersions } from "./versions.js";
 
 /** Register every Skill-domain tool; returns the registered tool names. */
 export function registerSkillTools(server: McpServer, target: BackendTarget): string[] {
@@ -63,5 +64,37 @@ export function registerSkillTools(server: McpServer, target: BackendTarget): st
       ),
   );
 
-  return ["get_skill", "delete_skill"];
+  server.registerTool(
+    "list_skill_versions",
+    {
+      description:
+        "List a skill's version history (newest first): version hash, tag, who pushed it and " +
+        "when, and which version is current. Fetch one version's full content with get_skill and " +
+        "its hash or tag.",
+      inputSchema: {
+        org: z.string().describe("Organization slug that owns the skill."),
+        slug: z.string().describe("Skill slug — unique identifier within the org."),
+        page_size: z
+          .number()
+          .int()
+          .optional()
+          .describe("Maximum versions per page (default 50)."),
+        page_token: z
+          .string()
+          .optional()
+          .describe("Pagination token from a previous response's next_page_token."),
+      },
+    },
+    (args, extra) =>
+      textOrError(() =>
+        listSkillVersions(target.serverAddress, resolveToken(extra, target.apiKey), {
+          org: args.org,
+          slug: args.slug,
+          pageSize: args.page_size,
+          pageToken: args.page_token,
+        }),
+      ),
+  );
+
+  return ["get_skill", "delete_skill", "list_skill_versions"];
 }

package/src/domains/skills/versions.ts

@@ -0,0 +1,47 @@
+// Skill version-timeline path (SkillQueryController.listVersions). Each push
+// creates an immutable version identified by the artifact's SHA-256 hash;
+// entries carry hash, tag, push audit, and provenance (no artifact content, so
+// no projection is needed — unlike the workflow timeline).
+
+import type { MessageInitShape } from "@bufbuild/protobuf";
+import {
+  type ListSkillVersionsInputSchema,
+  ListSkillVersionsResponseSchema,
+} from "@stigmer/protos/ai/stigmer/agentic/skill/v1/io_pb";
+import { SkillQueryController } from "@stigmer/protos/ai/stigmer/agentic/skill/v1/query_pb";
+
+import { withClient } from "../client.js";
+import { toProtoJson } from "../marshal.js";
+import { rpcError } from "../rpcerr.js";
+
+export interface ListSkillVersionsArgs {
+  readonly org: string;
+  readonly slug: string;
+  readonly pageSize?: number;
+  readonly pageToken?: string;
+}
+
+/** List a skill's version history (newest first) as protojson. */
+export async function listSkillVersions(
+  serverAddress: string,
+  token: string,
+  args: ListSkillVersionsArgs,
+): Promise<string> {
+  return withClient(SkillQueryController, serverAddress, token, async (client, callOptions) => {
+    const req: MessageInitShape<typeof ListSkillVersionsInputSchema> = {
+      org: args.org,
+      slug: args.slug,
+      pageToken: args.pageToken ?? "",
+    };
+    // Forward page_size only when set, letting the server apply its default.
+    if ((args.pageSize ?? 0) > 0) {
+      req.pageSize = args.pageSize;
+    }
+    try {
+      const resp = await client.listVersions(req, callOptions);
+      return toProtoJson(ListSkillVersionsResponseSchema, resp);
+    } catch (err) {
+      throw rpcError(err, `versions of skill "${args.slug}" in org "${args.org}"`);
+    }
+  });
+}

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

@@ -0,0 +1,212 @@
+// In-process integration test for the versioning tools: list_workflow_versions
+// (timeline projection — validated_yaml stripped), get_workflow's version
+// argument (slug→ID two-step into getVersion), tag_workflow_version, and
+// list_skill_versions. Same harness as reads.integration.test.ts.
+
+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 { SkillQueryController } from "@stigmer/protos/ai/stigmer/agentic/skill/v1/query_pb";
+import {
+  ListSkillVersionsResponseSchema,
+  type ListSkillVersionsInput,
+} from "@stigmer/protos/ai/stigmer/agentic/skill/v1/io_pb";
+import { WorkflowSchema } from "@stigmer/protos/ai/stigmer/agentic/workflow/v1/api_pb";
+import { WorkflowCommandController } from "@stigmer/protos/ai/stigmer/agentic/workflow/v1/command_pb";
+import { WorkflowQueryController } from "@stigmer/protos/ai/stigmer/agentic/workflow/v1/query_pb";
+import {
+  ListWorkflowVersionsResponseSchema,
+  WorkflowVersionEntrySchema,
+  type GetWorkflowVersionInput,
+  type TagWorkflowVersionInput,
+} from "@stigmer/protos/ai/stigmer/agentic/workflow/v1/version_pb";
+import { afterAll, beforeAll, beforeEach, describe, expect, it } from "vitest";
+
+import { configureLogger } from "../logger";
+import { createServer } from "../server";
+
+configureLogger({ level: "error", format: "text" });
+
+const HASH_A = "a".repeat(64);
+const HASH_B = "b".repeat(64);
+
+const knownWorkflow = create(WorkflowSchema, {
+  apiVersion: "v1",
+  kind: "workflow",
+  metadata: { name: "Release", slug: "release", org: "acme", id: "wkf_1" },
+});
+
+const workflowVersions = create(ListWorkflowVersionsResponseSchema, {
+  versions: [
+    { versionHash: HASH_A, tag: "stable", isCurrent: true, validatedYaml: "document: {}" },
+    { versionHash: HASH_B, validatedYaml: "document: {old: true}" },
+  ],
+  totalCount: 2,
+});
+
+const versionEntry = create(WorkflowVersionEntrySchema, {
+  versionHash: HASH_B,
+  validatedYaml: "document: {old: true}",
+});
+
+const skillVersions = create(ListSkillVersionsResponseSchema, {
+  versions: [{ versionHash: HASH_A, tag: "stable", isCurrent: true }],
+  totalCount: 1,
+});
+
+let backend: Http2Server;
+let client: Client;
+let lastGetVersion: GetWorkflowVersionInput | undefined;
+let lastTagVersion: TagWorkflowVersionInput | undefined;
+let lastSkillVersionsRequest: ListSkillVersionsInput | undefined;
+const openSessions = new Set<ServerHttp2Session>();
+
+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(WorkflowQueryController, {
+      getByReference: () => knownWorkflow,
+      listVersions: () => workflowVersions,
+      getVersion: (req) => {
+        lastGetVersion = req;
+        return versionEntry;
+      },
+    });
+    router.service(WorkflowCommandController, {
+      tagVersion: (req) => {
+        lastTagVersion = req;
+        return knownWorkflow;
+      },
+    });
+    router.service(SkillQueryController, {
+      listVersions: (req) => {
+        lastSkillVersionsRequest = req;
+        return skillVersions;
+      },
+    });
+  };
+  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: "versions-integration", version: "test" });
+  await Promise.all([mcp.connect(serverTransport), client.connect(clientTransport)]);
+});
+
+beforeEach(() => {
+  lastGetVersion = undefined;
+  lastTagVersion = undefined;
+  lastSkillVersionsRequest = undefined;
+});
+
+afterAll(async () => {
+  await client?.close();
+  for (const session of openSessions) session.destroy();
+  await new Promise<void>((resolve) => backend.close(() => resolve()));
+});
+
+describe("versioning tools integration", () => {
+  it("advertises the versioning tools", async () => {
+    const { tools } = await client.listTools();
+    expect(tools.map((t) => t.name)).toEqual(
+      expect.arrayContaining([
+        "list_workflow_versions",
+        "tag_workflow_version",
+        "list_skill_versions",
+      ]),
+    );
+  });
+
+  it("list_workflow_versions strips validated_yaml from the timeline", async () => {
+    const result = await callTool("list_workflow_versions", { org: "acme", slug: "release" });
+    expect(result.isError).toBeFalsy();
+
+    const body = parseText(result);
+    expect(body.total_count).toBe(2);
+    const versions = body.versions as Array<Record<string, unknown>>;
+    expect(versions).toHaveLength(2);
+    expect(versions[0]).toMatchObject({ version_hash: HASH_A, tag: "stable", is_current: true });
+    for (const entry of versions) {
+      expect(entry.validated_yaml).toBeUndefined();
+    }
+  });
+
+  it("get_workflow with a version resolves the id and fetches that version", async () => {
+    const result = await callTool("get_workflow", {
+      org: "acme",
+      slug: "release",
+      version: HASH_B,
+    });
+    expect(result.isError).toBeFalsy();
+    expect(lastGetVersion?.workflowId).toBe("wkf_1");
+    expect(lastGetVersion?.versionHash).toBe(HASH_B);
+    // The version entry carries the YAML the timeline omits.
+    expect(parseText(result)).toEqual(
+      toJson(WorkflowVersionEntrySchema, versionEntry, { useProtoFieldName: true }),
+    );
+  });
+
+  it("get_workflow without a version returns the live workflow", async () => {
+    const result = await callTool("get_workflow", { org: "acme", slug: "release" });
+    expect(result.isError).toBeFalsy();
+    expect(lastGetVersion).toBeUndefined();
+    expect(parseText(result)).toEqual(
+      toJson(WorkflowSchema, knownWorkflow, { useProtoFieldName: true }),
+    );
+  });
+
+  it("tag_workflow_version resolves the id and forwards hash and tag", async () => {
+    const result = await callTool("tag_workflow_version", {
+      org: "acme",
+      slug: "release",
+      version: HASH_B,
+      tag: "stable",
+    });
+    expect(result.isError).toBeFalsy();
+    expect(lastTagVersion?.workflowId).toBe("wkf_1");
+    expect(lastTagVersion?.versionHash).toBe(HASH_B);
+    expect(lastTagVersion?.tag).toBe("stable");
+  });
+
+  it("list_skill_versions forwards the reference and returns the timeline", async () => {
+    const result = await callTool("list_skill_versions", {
+      org: "acme",
+      slug: "code-review",
+      page_size: 10,
+    });
+    expect(result.isError).toBeFalsy();
+    expect(lastSkillVersionsRequest?.org).toBe("acme");
+    expect(lastSkillVersionsRequest?.slug).toBe("code-review");
+    expect(lastSkillVersionsRequest?.pageSize).toBe(10);
+    expect(parseText(result)).toEqual(
+      toJson(ListSkillVersionsResponseSchema, skillVersions, { useProtoFieldName: true }),
+    );
+  });
+});

package/src/domains/workflowexecutions/approvals.ts

@@ -0,0 +1,102 @@
+// Workflow-execution approval paths: the org-wide pending-approvals inbox
+// (listPendingApprovals) and the reviewer decision for a human_input task
+// (submitWorkflowTaskApproval).
+//
+// listPendingApprovals is org-scoped by contract (io.proto), not
+// execution-scoped — it answers "what is waiting on a human right now"
+// across the org. Each entry carries everything a decision needs: the
+// execution ID, task name, requester, timeout, and the form schema when the
+// task defines one. Agent-execution approvals are a different surface
+// entirely (embedded in get_agent_execution status; see
+// agentexecutions/approve.ts).
+
+import type { JsonObject, MessageInitShape } from "@bufbuild/protobuf";
+import { WorkflowExecutionSchema } from "@stigmer/protos/ai/stigmer/agentic/workflowexecution/v1/api_pb";
+import { WorkflowExecutionCommandController } from "@stigmer/protos/ai/stigmer/agentic/workflowexecution/v1/command_pb";
+import {
+  type ListPendingApprovalsRequestSchema,
+  PendingApprovalsListSchema,
+  type SubmitWorkflowTaskApprovalInputSchema,
+} from "@stigmer/protos/ai/stigmer/agentic/workflowexecution/v1/io_pb";
+import { WorkflowExecutionQueryController } from "@stigmer/protos/ai/stigmer/agentic/workflowexecution/v1/query_pb";
+
+import { withClient } from "../client.js";
+import { toProtoJson } from "../marshal.js";
+import { rpcError } from "../rpcerr.js";
+
+export interface ListPendingApprovalsArgs {
+  readonly org: string;
+  readonly pageSize?: number;
+  readonly pageToken?: string;
+}
+
+/** List human_input tasks awaiting a reviewer decision across an org. */
+export async function listPendingApprovals(
+  serverAddress: string,
+  token: string,
+  args: ListPendingApprovalsArgs,
+): Promise<string> {
+  return withClient(
+    WorkflowExecutionQueryController,
+    serverAddress,
+    token,
+    async (client, callOptions) => {
+      const req: MessageInitShape<typeof ListPendingApprovalsRequestSchema> = {
+        org: args.org,
+        pageToken: args.pageToken ?? "",
+      };
+      // Forward page_size only when set, letting the server apply its default.
+      if ((args.pageSize ?? 0) > 0) {
+        req.pageSize = args.pageSize;
+      }
+      try {
+        const resp = await client.listPendingApprovals(req, callOptions);
+        return toProtoJson(PendingApprovalsListSchema, resp);
+      } catch (err) {
+        throw rpcError(err, `pending approvals in org "${args.org}"`);
+      }
+    },
+  );
+}
+
+export interface SubmitWorkflowTaskApprovalArgs {
+  readonly executionId: string;
+  readonly taskName: string;
+  readonly outcome: string;
+  readonly comment?: string;
+  readonly formData?: Record<string, unknown>;
+}
+
+/** Submit a reviewer decision for a waiting human_input task. */
+export async function submitWorkflowTaskApproval(
+  serverAddress: string,
+  token: string,
+  args: SubmitWorkflowTaskApprovalArgs,
+): Promise<string> {
+  return withClient(
+    WorkflowExecutionCommandController,
+    serverAddress,
+    token,
+    async (client, callOptions) => {
+      const req: MessageInitShape<typeof SubmitWorkflowTaskApprovalInputSchema> = {
+        executionId: args.executionId,
+        taskName: args.taskName,
+        outcome: args.outcome,
+        comment: args.comment ?? "",
+      };
+      if (args.formData !== undefined) {
+        // google.protobuf.Struct fields are plain JSON objects in protobuf-es v2.
+        req.formData = args.formData as JsonObject;
+      }
+      try {
+        const execution = await client.submitWorkflowTaskApproval(req, callOptions);
+        return toProtoJson(WorkflowExecutionSchema, execution);
+      } catch (err) {
+        throw rpcError(
+          err,
+          `approval for task "${args.taskName}" in workflow execution "${args.executionId}"`,
+        );
+      }
+    },
+  );
+}