@stigmer/mcp-server 3.0.8-dev.20260612122433

package/src/domains/workflows/validate.integration.test.ts

@@ -0,0 +1,117 @@
+// In-process integration test for validate_workflow_yaml. Verifies the
+// required-yaml and parse errors, that every registry task kind (including
+// `eval`, which the Go map omits) is accepted, and that the parsed Workflow is
+// forwarded to validateSpec.
+
+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 { WorkflowCommandController } from "@stigmer/protos/ai/stigmer/agentic/workflow/v1/command_pb";
+import { WorkflowTaskKind } from "@stigmer/protos/ai/stigmer/agentic/workflow/v1/enum_pb";
+import { ServerlessWorkflowValidationSchema } from "@stigmer/protos/ai/stigmer/agentic/workflow/v1/serverless/validation_pb";
+import type { Workflow } from "@stigmer/protos/ai/stigmer/agentic/workflow/v1/api_pb";
+import { afterAll, beforeAll, describe, expect, it } from "vitest";
+import { stringify as stringifyYaml } from "yaml";
+
+import { configureLogger } from "../../logger";
+import { createServer } from "../../server";
+
+configureLogger({ level: "error", format: "text" });
+
+const registryKinds = Object.values(WorkflowTaskKind).filter(
+  (v): v is string => typeof v === "string" && v !== "workflow_task_kind_unspecified",
+);
+const validation = create(ServerlessWorkflowValidationSchema, {});
+
+let backend: Http2Server;
+let client: Client;
+let lastWorkflow: Workflow | undefined;
+const openSessions = new Set<ServerHttp2Session>();
+
+interface ToolResult {
+  content: Array<{ type: string; text?: string }>;
+  isError?: boolean;
+}
+
+async function validate(yaml: string): Promise<ToolResult> {
+  return (await client.callTool({ name: "validate_workflow_yaml", arguments: { yaml } })) as ToolResult;
+}
+
+beforeAll(async () => {
+  const routes = (router: ConnectRouter) => {
+    router.service(WorkflowCommandController, {
+      validateSpec: (req) => {
+        lastWorkflow = req;
+        return validation;
+      },
+    });
+  };
+  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: "validate-integration", version: "test" });
+  await Promise.all([mcp.connect(serverTransport), client.connect(clientTransport)]);
+});
+
+afterAll(async () => {
+  await client?.close();
+  for (const session of openSessions) session.destroy();
+  await new Promise<void>((resolve) => backend.close(() => resolve()));
+});
+
+describe("validate_workflow_yaml integration", () => {
+  it("requires non-empty yaml", async () => {
+    const result = await validate("   ");
+    expect(result.isError).toBe(true);
+    expect(result.content[0]?.text).toContain("yaml is required");
+  });
+
+  it("rejects yaml without a spec", async () => {
+    const result = await validate(stringifyYaml({ apiVersion: "v1", kind: "workflow" }));
+    expect(result.isError).toBe(true);
+    expect(result.content[0]?.text).toContain(
+      "failed to parse workflow YAML: missing or invalid 'spec' field",
+    );
+  });
+
+  it("rejects an unknown task kind with its index", async () => {
+    const doc = { spec: { tasks: [{ name: "t0", kind: "bogus_kind" }] } };
+    const result = await validate(stringifyYaml(doc));
+    expect(result.isError).toBe(true);
+    expect(result.content[0]?.text).toContain(
+      'failed to parse workflow YAML: unknown task kind "bogus_kind" at tasks[0]',
+    );
+  });
+
+  it("accepts every registry task kind (including eval) and forwards the workflow", async () => {
+    const doc = {
+      apiVersion: "v1",
+      kind: "workflow",
+      metadata: { name: "wf", org: "acme", slug: "wf" },
+      spec: { tasks: registryKinds.map((kind, i) => ({ name: `t${i}`, kind })) },
+    };
+    const result = await validate(stringifyYaml(doc));
+    expect(result.isError).toBeFalsy();
+    expect(JSON.parse(result.content[0]?.text ?? "{}")).toEqual(
+      toJson(ServerlessWorkflowValidationSchema, validation, { useProtoFieldName: true }),
+    );
+    expect(lastWorkflow?.spec?.tasks.length).toBe(registryKinds.length);
+    expect(lastWorkflow?.spec?.tasks.some((t) => t.kind === WorkflowTaskKind.eval)).toBe(true);
+  });
+});

package/src/domains/workflows/validate.ts

@@ -0,0 +1,144 @@
+// The validate_workflow_yaml tool.
+// Go parity: mcp-server/internal/domains/workflows/validate.go.
+//
+// The YAML is parsed to a Workflow proto locally (string task kinds are checked
+// against the accepted set), then validated server-side via
+// WorkflowCommandController.validateSpec — the same Temporal-based pipeline used
+// by workflow create/update.
+//
+// Parity note (Go D4): the Go server's taskKindNameToEnum map is an identity map
+// that omits `eval`, so Go rejects valid `eval` tasks. We derive the accepted
+// set directly from the WorkflowTaskKind enum's value names instead — identical
+// behavior for the other 19 kinds AND correct for `eval`. Flagged for the Go
+// side as a T03 follow-up.
+
+import { fromJson, type JsonValue } from "@bufbuild/protobuf";
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { type Workflow, WorkflowSchema } from "@stigmer/protos/ai/stigmer/agentic/workflow/v1/api_pb";
+import { WorkflowCommandController } from "@stigmer/protos/ai/stigmer/agentic/workflow/v1/command_pb";
+import { WorkflowTaskKind } from "@stigmer/protos/ai/stigmer/agentic/workflow/v1/enum_pb";
+import { ServerlessWorkflowValidationSchema } from "@stigmer/protos/ai/stigmer/agentic/workflow/v1/serverless/validation_pb";
+import { z } from "zod";
+import { parse as parseYaml } from "yaml";
+
+import { resolveToken, withClient, type BackendTarget } from "../client.js";
+import { toProtoJson } from "../marshal.js";
+import { rpcError } from "../rpcerr.js";
+import { textOrError } from "../toolresult.js";
+
+/**
+ * The task kinds the YAML may declare, derived from the proto enum (every value
+ * except the unspecified zero value). Deriving from the enum keeps this in lock
+ * step with the contract and avoids a hand-maintained list.
+ */
+const acceptedTaskKinds: ReadonlySet<string> = new Set(
+  Object.values(WorkflowTaskKind).filter(
+    (v): v is string => typeof v === "string" && v !== "workflow_task_kind_unspecified",
+  ),
+);
+
+/** Register the validate_workflow_yaml tool; returns the registered tool names. */
+export function registerValidateWorkflowYamlTool(
+  server: McpServer,
+  target: BackendTarget,
+): string[] {
+  server.registerTool(
+    "validate_workflow_yaml",
+    {
+      description:
+        "Validate a Stigmer workflow YAML for structural and semantic correctness. " +
+        "Uses the same Temporal-based validation pipeline as workflow create/update. " +
+        "Returns validation state (VALID/INVALID/FAILED), errors, warnings, and the generated internal YAML.",
+      inputSchema: {
+        yaml: z
+          .string()
+          .describe(
+            "Complete Stigmer workflow YAML content to validate (apiVersion, kind, metadata, spec).",
+          ),
+      },
+    },
+    (args, extra) =>
+      textOrError(() =>
+        validateWorkflowYaml(target.serverAddress, resolveToken(extra, target.apiKey), args.yaml),
+      ),
+  );
+
+  return ["validate_workflow_yaml"];
+}
+
+/** Parse the YAML to a Workflow proto, then validate it server-side. */
+async function validateWorkflowYaml(
+  serverAddress: string,
+  token: string,
+  yamlContent: string,
+): Promise<string> {
+  if (yamlContent.trim() === "") {
+    throw new Error("yaml is required");
+  }
+
+  let workflow: Workflow;
+  try {
+    workflow = parseWorkflowYaml(yamlContent);
+  } catch (err) {
+    throw new Error(`failed to parse workflow YAML: ${errMessage(err)}`);
+  }
+
+  return withClient(WorkflowCommandController, serverAddress, token, async (client, callOptions) => {
+    try {
+      const validation = await client.validateSpec(workflow, callOptions);
+      return toProtoJson(ServerlessWorkflowValidationSchema, validation);
+    } catch (err) {
+      throw rpcError(err, "workflow validation");
+    }
+  });
+}
+
+/**
+ * Convert a Stigmer workflow YAML string to a Workflow proto. The YAML has an
+ * apiVersion/kind/metadata/spec shape; task kinds are validated against the
+ * accepted set. task_config is a google.protobuf.Struct and round-trips through
+ * JSON naturally.
+ */
+function parseWorkflowYaml(yamlContent: string): Workflow {
+  let raw: unknown;
+  try {
+    raw = parseYaml(yamlContent);
+  } catch (err) {
+    throw new Error(`invalid YAML syntax: ${errMessage(err)}`);
+  }
+
+  if (!isObject(raw)) {
+    throw new Error("missing or invalid 'spec' field");
+  }
+  const spec = raw.spec;
+  if (!isObject(spec)) {
+    throw new Error("missing or invalid 'spec' field");
+  }
+
+  const tasks = spec.tasks;
+  if (Array.isArray(tasks)) {
+    tasks.forEach((task, i) => {
+      if (!isObject(task)) {
+        return;
+      }
+      const kind = task.kind;
+      if (typeof kind === "string" && kind !== "" && !acceptedTaskKinds.has(kind)) {
+        throw new Error(`unknown task kind "${kind}" at tasks[${i}]`);
+      }
+    });
+  }
+
+  try {
+    return fromJson(WorkflowSchema, raw as JsonValue, { ignoreUnknownFields: true });
+  } catch (err) {
+    throw new Error(`failed to unmarshal into Workflow proto: ${errMessage(err)}`);
+  }
+}
+
+function isObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function errMessage(err: unknown): string {
+  return err instanceof Error ? err.message : String(err);
+}

package/src/domains/workflows/workflow-tools.integration.test.ts

@@ -0,0 +1,148 @@
+// In-process integration test for the workflow query tools: the task-kind
+// registry pair (get_task_kind_registry, get_task_kind) and the execution pair
+// (get_workflow_execution, get_workflow_execution_events). Verifies registry
+// selection (case-insensitive), the required-field and not-found errors, and
+// that page_size is forwarded only when set.
+
+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 { WorkflowTaskKind } from "@stigmer/protos/ai/stigmer/agentic/workflow/v1/enum_pb";
+import {
+  GetTaskKindRegistryResponseSchema,
+  TaskKindDescriptorSchema,
+} from "@stigmer/protos/ai/stigmer/agentic/workflow/v1/task_kind_descriptor_pb";
+import { TaskKindRegistryQueryController } from "@stigmer/protos/ai/stigmer/agentic/workflow/v1/task_kind_registry_query_pb";
+import { WorkflowExecutionSchema } from "@stigmer/protos/ai/stigmer/agentic/workflowexecution/v1/api_pb";
+import {
+  type GetEventLogRequest,
+  GetEventLogResponseSchema,
+} 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, describe, expect, it } from "vitest";
+
+import { configureLogger } from "../../logger";
+import { createServer } from "../../server";
+
+configureLogger({ level: "error", format: "text" });
+
+const registry = create(GetTaskKindRegistryResponseSchema, {
+  descriptors: [
+    create(TaskKindDescriptorSchema, { kind: WorkflowTaskKind.set_vars }),
+    create(TaskKindDescriptorSchema, { kind: WorkflowTaskKind.for_each }),
+  ],
+});
+const execution = create(WorkflowExecutionSchema, { apiVersion: "v1", kind: "workflow_execution" });
+const eventLog = create(GetEventLogResponseSchema, {});
+
+let backend: Http2Server;
+let client: Client;
+let lastExecutionId: string | undefined;
+let lastEventReq: GetEventLogRequest | 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;
+}
+
+beforeAll(async () => {
+  const routes = (router: ConnectRouter) => {
+    router.service(TaskKindRegistryQueryController, { getTaskKindRegistry: () => registry });
+    router.service(WorkflowExecutionQueryController, {
+      get: (req) => {
+        lastExecutionId = req.value;
+        return execution;
+      },
+      getEventLog: (req) => {
+        lastEventReq = req;
+        return eventLog;
+      },
+    });
+  };
+  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: "workflow-tools-integration", version: "test" });
+  await Promise.all([mcp.connect(serverTransport), client.connect(clientTransport)]);
+});
+
+afterAll(async () => {
+  await client?.close();
+  for (const session of openSessions) session.destroy();
+  await new Promise<void>((resolve) => backend.close(() => resolve()));
+});
+
+describe("workflow query tools integration", () => {
+  it("get_task_kind_registry returns the full registry", async () => {
+    const result = await callTool("get_task_kind_registry", {});
+    expect(result.isError).toBeFalsy();
+    expect(JSON.parse(result.content[0]?.text ?? "{}")).toEqual(
+      toJson(GetTaskKindRegistryResponseSchema, registry, { useProtoFieldName: true }),
+    );
+  });
+
+  it("get_task_kind selects one descriptor case-insensitively", async () => {
+    const result = await callTool("get_task_kind", { kind: "FOR_EACH" });
+    expect(result.isError).toBeFalsy();
+    expect(JSON.parse(result.content[0]?.text ?? "{}")).toEqual(
+      toJson(TaskKindDescriptorSchema, registry.descriptors[1]!, { useProtoFieldName: true }),
+    );
+  });
+
+  it("get_task_kind requires a kind", async () => {
+    const result = await callTool("get_task_kind", { kind: "" });
+    expect(result.isError).toBe(true);
+    expect(result.content[0]?.text).toContain("kind is required");
+  });
+
+  it("get_task_kind reports an unknown kind", async () => {
+    const result = await callTool("get_task_kind", { kind: "does_not_exist" });
+    expect(result.isError).toBe(true);
+    expect(result.content[0]?.text).toContain('task kind "does_not_exist" not found in registry');
+  });
+
+  it("get_workflow_execution requires an execution_id", async () => {
+    const result = await callTool("get_workflow_execution", { execution_id: "" });
+    expect(result.isError).toBe(true);
+    expect(result.content[0]?.text).toContain("execution_id is required");
+  });
+
+  it("get_workflow_execution forwards the id and returns the execution", async () => {
+    const result = await callTool("get_workflow_execution", { execution_id: "wex_123" });
+    expect(result.isError).toBeFalsy();
+    expect(lastExecutionId).toBe("wex_123");
+    expect(JSON.parse(result.content[0]?.text ?? "{}")).toEqual(
+      toJson(WorkflowExecutionSchema, execution, { useProtoFieldName: true }),
+    );
+  });
+
+  it("get_workflow_execution_events forwards page_size only when set", async () => {
+    await callTool("get_workflow_execution_events", { execution_id: "wex_123", task_name: "build" });
+    expect(lastEventReq?.taskName).toBe("build");
+    expect(lastEventReq?.pageSize).toBe(0);
+
+    await callTool("get_workflow_execution_events", { execution_id: "wex_123", page_size: 50 });
+    expect(lastEventReq?.pageSize).toBe(50);
+  });
+});

package/src/gen/agent.ts

@@ -0,0 +1,173 @@
+// Code generated by stigmer-codegen --target=mcp-ts. DO NOT EDIT.
+//
+// Flattened apply-input zod schema + toProto bridge for the Agent resource.
+// Source proto package: ai.stigmer.agentic.agent.v1
+
+import { generateSlug, visibilityFromString } from "./apply-runtime.js";
+import { create } from "@bufbuild/protobuf";
+import { AgentSchema, type Agent } from "@stigmer/protos/ai/stigmer/agentic/agent/v1/api_pb";
+import { AgentSpecSchema, ToolApprovalOverrideSchema, McpServerUsageSchema, McpAccessSchema, SubAgentSchema } from "@stigmer/protos/ai/stigmer/agentic/agent/v1/spec_pb";
+import { EnvVarDeclarationSchema } from "@stigmer/protos/ai/stigmer/agentic/environment/v1/spec_pb";
+import { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
+import { ApiResourceReferenceSchema } from "@stigmer/protos/ai/stigmer/commons/apiresource/io_pb";
+import { ApiResourceMetadataSchema } from "@stigmer/protos/ai/stigmer/commons/apiresource/metadata_pb";
+import { z } from "zod";
+
+/** AgentSpec defines the configurable properties of an agent. @internal This is the "Template" layer — declares capabilities and requirements. The overview.md file provides the SDK-facing description and example YAML. */
+export const AgentInputShape = {
+  name: z.string().describe("Human-readable name of the resource."),
+  slug: z.string().optional().describe("URL-friendly identifier (lowercase alphanumeric with hyphens). Auto-generated from name if omitted."),
+  org: z.string().describe("Organization that owns this resource (e.g. acme)."),
+  visibility: z.string().optional().describe("Resource visibility: PRIVATE or PUBLIC. Omit to leave unchanged on updates."),
+  labels: z.record(z.string()).optional().describe("Key-value labels for organization and filtering."),
+  tags: z.array(z.string()).optional().describe("Tags for categorization and discovery."),
+  description: z.string().optional().describe("Human-readable description for UI and marketplace display."),
+  icon_url: z.string().optional().describe("Icon URL for marketplace and UI display. Must be a publicly accessible URL to an image (SVG, PNG, or JPEG)."),
+  instructions: z.string().optional().describe("System prompt defining the agent's behavior and personality."),
+  mcp_server_usages: z.array(z.lazy(() => McpServerUsageInputSchema)).optional().describe("MCP servers this agent can use. Each entry must reference a unique McpServer resource by slug."),
+  skill_refs: z.array(z.lazy(() => SkillRefInputSchema)).optional().describe("Skill resources providing additional knowledge to the agent."),
+  sub_agents: z.array(z.lazy(() => SubAgentInputSchema)).optional().describe("Sub-agents that can be delegated to. Sub-agents can access a subset of the parent's MCP servers and tools."),
+  env: z.record(z.lazy(() => EnvVarDeclarationInputSchema)).optional().describe("Environment variable declarations for this agent. Keys are variable names; values describe their metadata and optionality."),
+} as const;
+
+export const AgentInputSchema = z.object(AgentInputShape);
+export type AgentInput = z.infer<typeof AgentInputSchema>;
+
+const McpServerRefInputSchema = z.object({
+  org: z.string().optional().describe("Organization that owns the referenced resource. When non-empty: must be a valid org slug (lowercase alphanumeric with hyphens, starts with a letter, 1-63 characters). Example: 'stigmer', 'acme-corp'. When empty: the reference is relative — the server resolves it to the parent resource's organization at write time. All stored and returned references always have org populated (absolute form). Use empty org for same-org references (the common case). Use explicit org for cross-org references (e.g., marketplace resources)."),
+  slug: z.string().describe("Resource slug (user-friendly identifier, unique within org). Format: lowercase alphanumeric with hyphens, must start with a letter and end with a letter or digit (e.g., 'web-search', 'code-reviewer'). Length: 2-63 characters."),
+});
+type McpServerRefInput = z.infer<typeof McpServerRefInputSchema>;
+
+const ToolApprovalOverrideInputSchema = z.object({
+  tool_name: z.string().optional().describe("Name of the tool to override."),
+  requires_approval: z.boolean().optional().describe("Whether this tool requires approval for this agent."),
+  message: z.string().optional().describe("Custom approval message shown to the reviewer. Supports {{args.field}} placeholders. When empty, falls back to the McpServer default or auto-generates 'Execute tool: {tool_name}'."),
+});
+type ToolApprovalOverrideInput = z.infer<typeof ToolApprovalOverrideInputSchema>;
+
+const McpServerUsageInputSchema = z.object({
+  mcp_server_ref: z.lazy(() => McpServerRefInputSchema).describe("Reference to the McpServer resource."),
+  enabled_tools: z.array(z.string()).optional().describe("Tools to enable from this MCP server for this agent. Empty list uses the McpServer's default_enabled_tools. Sub-agents can only restrict this set further, not expand it. @internal Tool names must match exactly what the MCP server reports via tools/list. Only names from discovered_capabilities.tools are valid here. Do NOT include names from discovered_capabilities.resource_templates — resource templates are read-only data endpoints, not callable tools. Including a resource template name here causes a fatal runtime error."),
+  tool_approval_overrides: z.array(z.lazy(() => ToolApprovalOverrideInputSchema)).optional().describe("Override approval requirements for specific tools. Takes precedence over McpServerSpec.pinned_tool_approvals and McpServerStatus.tool_approvals."),
+});
+type McpServerUsageInput = z.infer<typeof McpServerUsageInputSchema>;
+
+const SkillRefInputSchema = z.object({
+  org: z.string().optional().describe("Organization that owns the referenced resource. When non-empty: must be a valid org slug (lowercase alphanumeric with hyphens, starts with a letter, 1-63 characters). Example: 'stigmer', 'acme-corp'. When empty: the reference is relative — the server resolves it to the parent resource's organization at write time. All stored and returned references always have org populated (absolute form). Use empty org for same-org references (the common case). Use explicit org for cross-org references (e.g., marketplace resources)."),
+  slug: z.string().describe("Resource slug (user-friendly identifier, unique within org). Format: lowercase alphanumeric with hyphens, must start with a letter and end with a letter or digit (e.g., 'web-search', 'code-reviewer'). Length: 2-63 characters."),
+  version: z.string().optional().describe("Version of the resource (optional, only applicable to versioned resources like Skills). Supports three formats: 1. Empty/unset → Resolves to 'latest' (most recent version) 2. Tag name → Resolves to version with this tag (e.g., 'stable', 'v1.0') 3. Exact hash → Immutable reference to specific version (e.g., 'abc123...') Default behavior: Empty means 'latest' (current version). This field is ignored for non-versioned resources. Examples: - version: '' → Use latest version - version: 'latest' → Use latest version (explicit) - version: 'stable' → Use version tagged as 'stable' - version: 'v1.0' → Use version tagged as 'v1.0' - version: 'abc123...' → Use exact version with this hash (immutable)"),
+});
+type SkillRefInput = z.infer<typeof SkillRefInputSchema>;
+
+const McpAccessInputSchema = z.object({
+  mcp_server: z.string().describe("Slug of the McpServer to grant access to. Must match a mcp_server_ref.slug from the parent's mcp_server_usages."),
+  enabled_tools: z.array(z.string()).optional().describe("Tools this sub-agent can use from this MCP server. Must be a subset of the parent's enabled_tools for this server. Empty list grants access to all tools the parent has enabled."),
+});
+type McpAccessInput = z.infer<typeof McpAccessInputSchema>;
+
+const SubAgentInputSchema = z.object({
+  name: z.string().describe("Unique name of the sub-agent within the parent agent."),
+  description: z.string().optional().describe("What this sub-agent specializes in."),
+  instructions: z.string().optional().describe("System prompt for this sub-agent."),
+  mcp_access: z.array(z.lazy(() => McpAccessInputSchema)).optional().describe("MCP server access grants for this sub-agent. Each entry references a parent McpServerUsage by slug and optionally restricts which tools are available."),
+  skill_refs: z.array(z.lazy(() => SkillRefInputSchema)).optional().describe("Skill resources for this sub-agent."),
+  model_override: z.string().optional().describe("Model override for this sub-agent. When set, uses this model instead of the parent's model. When empty, inherits the parent agent's model."),
+});
+type SubAgentInput = z.infer<typeof SubAgentInputSchema>;
+
+const EnvVarDeclarationInputSchema = z.object({
+  is_secret: z.boolean().optional().describe("Whether the resolved value should be treated as a secret. @internal When true: encrypted at rest, redacted in logs and Temporal history. When false: stored as plaintext, visible in audit logs."),
+  description: z.string().optional().describe("Human-readable description shown in the UI credential form. Should explain what the variable is used for and where to obtain it."),
+  optional: z.boolean().optional().describe("Whether this variable is optional. @internal When false (default): the execution pipeline rejects a run if this variable is missing from the user's environment. When true: a missing value is acceptable (the MCP server or agent degrades gracefully without it)."),
+});
+type EnvVarDeclarationInput = z.infer<typeof EnvVarDeclarationInputSchema>;
+
+
+/** Build the fully-formed Agent proto from the flat MCP apply input. */
+export function agentInputToProto(input: AgentInput): Agent {
+  const slug = input.slug && input.slug.length > 0 ? input.slug : generateSlug(input.name);
+  const spec = create(AgentSpecSchema);
+  if (input.description !== undefined) spec.description = input.description;
+  if (input.icon_url !== undefined) spec.iconUrl = input.icon_url;
+  if (input.instructions !== undefined) spec.instructions = input.instructions;
+  if (input.mcp_server_usages !== undefined) spec.mcpServerUsages = input.mcp_server_usages.map(mcpServerUsageInputToProto);
+  if (input.skill_refs !== undefined) spec.skillRefs = input.skill_refs.map(skillRefInputToProto);
+  if (input.sub_agents !== undefined) spec.subAgents = input.sub_agents.map(subAgentInputToProto);
+  if (input.env !== undefined) {
+    for (const [k, v] of Object.entries(input.env)) spec.env[k] = envVarDeclarationInputToProto(v);
+  }
+  return Object.assign(create(AgentSchema), {
+    apiVersion: "agentic.stigmer.ai/v1",
+    kind: "Agent",
+    metadata: Object.assign(create(ApiResourceMetadataSchema), {
+      name: input.name,
+      slug,
+      org: input.org,
+      ...(input.visibility !== undefined && { visibility: visibilityFromString(input.visibility) }),
+      ...(input.labels !== undefined && { labels: input.labels }),
+      ...(input.tags !== undefined && { tags: input.tags }),
+    }),
+    spec,
+  }) as Agent;
+}
+
+function mcpServerRefInputToProto(input: McpServerRefInput) {
+  return create(ApiResourceReferenceSchema, {
+    org: input.org,
+    slug: input.slug,
+    kind: ApiResourceKind.mcp_server,
+  });
+}
+
+function toolApprovalOverrideInputToProto(input: ToolApprovalOverrideInput) {
+  const result = create(ToolApprovalOverrideSchema);
+  if (input.tool_name !== undefined) result.toolName = input.tool_name;
+  if (input.requires_approval !== undefined) result.requiresApproval = input.requires_approval;
+  if (input.message !== undefined) result.message = input.message;
+  return result;
+}
+
+function mcpServerUsageInputToProto(input: McpServerUsageInput) {
+  const result = create(McpServerUsageSchema);
+  if (input.mcp_server_ref !== undefined) result.mcpServerRef = mcpServerRefInputToProto(input.mcp_server_ref);
+  if (input.enabled_tools !== undefined) result.enabledTools = input.enabled_tools;
+  if (input.tool_approval_overrides !== undefined) result.toolApprovalOverrides = input.tool_approval_overrides.map(toolApprovalOverrideInputToProto);
+  return result;
+}
+
+function skillRefInputToProto(input: SkillRefInput) {
+  return create(ApiResourceReferenceSchema, {
+    org: input.org,
+    slug: input.slug,
+    kind: ApiResourceKind.skill,
+    version: input.version,
+  });
+}
+
+function mcpAccessInputToProto(input: McpAccessInput) {
+  const result = create(McpAccessSchema);
+  if (input.mcp_server !== undefined) result.mcpServer = input.mcp_server;
+  if (input.enabled_tools !== undefined) result.enabledTools = input.enabled_tools;
+  return result;
+}
+
+function subAgentInputToProto(input: SubAgentInput) {
+  const result = create(SubAgentSchema);
+  if (input.name !== undefined) result.name = input.name;
+  if (input.description !== undefined) result.description = input.description;
+  if (input.instructions !== undefined) result.instructions = input.instructions;
+  if (input.mcp_access !== undefined) result.mcpAccess = input.mcp_access.map(mcpAccessInputToProto);
+  if (input.skill_refs !== undefined) result.skillRefs = input.skill_refs.map(skillRefInputToProto);
+  if (input.model_override !== undefined) result.modelOverride = input.model_override;
+  return result;
+}
+
+function envVarDeclarationInputToProto(input: EnvVarDeclarationInput) {
+  const result = create(EnvVarDeclarationSchema);
+  if (input.is_secret !== undefined) result.isSecret = input.is_secret;
+  if (input.description !== undefined) result.description = input.description;
+  if (input.optional !== undefined) result.optional = input.optional;
+  return result;
+}
+

package/src/gen/apply-runtime.ts

@@ -0,0 +1,52 @@
+// Code generated by stigmer-codegen --target=mcp-ts. DO NOT EDIT.
+//
+// Shared runtime helpers for the generated apply-input toProto bridges.
+
+import { timestampFromDate, type Timestamp } from "@bufbuild/protobuf/wkt";
+import { ApiResourceVisibility } from "@stigmer/protos/ai/stigmer/commons/apiresource/enum_pb";
+
+/**
+ * Slugify a resource name: lowercase, collapse each run of non-alphanumeric
+ * characters into a single hyphen, then trim leading/trailing hyphens.
+ */
+export function generateSlug(name: string): string {
+  if (!name) return "";
+  let out = "";
+  let lastHyphen = false;
+  for (const ch of name.toLowerCase()) {
+    if ((ch >= "a" && ch <= "z") || (ch >= "0" && ch <= "9")) {
+      out += ch;
+      lastHyphen = false;
+    } else if (!lastHyphen) {
+      out += "-";
+      lastHyphen = true;
+    }
+  }
+  return out.replace(/^-+/, "").replace(/-+$/, "");
+}
+
+/** Map the PUBLIC/PRIVATE apply input string to the visibility enum. */
+export function visibilityFromString(s: string | undefined): ApiResourceVisibility {
+  if (s && s.toUpperCase() === "PUBLIC") return ApiResourceVisibility.visibility_public;
+  if (s && s.toUpperCase() === "PRIVATE") return ApiResourceVisibility.visibility_private;
+  return ApiResourceVisibility.api_resource_visibility_unspecified;
+}
+
+/**
+ * Resolve an enum value-name string to its numeric value, leniently: an unknown
+ * or missing value yields 0 (the proto UNSPECIFIED sentinel), matching the Go
+ * generator's EnumType_value[input] lookup.
+ */
+export function enumFromString(
+  enumObj: Record<string, string | number>,
+  value: string | undefined,
+): number {
+  if (value === undefined) return 0;
+  const v = enumObj[value];
+  return typeof v === "number" ? v : 0;
+}
+
+/** Convert an ISO-8601 string to a protobuf Timestamp message. */
+export function toTimestamp(value: string): Timestamp {
+  return timestampFromDate(new Date(value));
+}