Express batch item references with oneOf

Model node, numeric, and issue references as closed schema variants while retaining runtime validation.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 7ae767ff-c1d0-46a9-b126-2e91403993a0

Author: zwick

README.md

@@ -1119,7 +1119,7 @@ The following sets of tools are available:
   - `item_owner`: The owner (user or organization) of the repository containing the issue or pull request. Required for 'add_project_item' method. Also accepted by 'update_project_item' when resolving the item by issue number. (string, optional)
   - `item_repo`: The name of the repository containing the issue or pull request. Required for 'add_project_item' method. Also accepted by 'update_project_item' when resolving the item by issue number. (string, optional)
   - `item_type`: The item's type, either issue or pull_request. Required for 'add_project_item' method. (string, optional)
-  - `items`: The set of items to update. Required for 'update_project_items'. Each entry references an existing item by exactly one of: 'node_id' (the item's GraphQL node ID, e.g. as returned by 'list_project_items' or 'add_project_item'), 'item_id' (the numeric project item ID), or (item_owner + item_repo + issue_number). Each entry may optionally include its own 'updated_field'; if omitted, the top-level 'updated_field' is applied. Limit: 100 items per call. (object[], optional)
+  - `items`: The items to update. Required for 'update_project_items'. Each entry must match exactly one reference variant: 'node_id', numeric 'item_id', or 'item_owner' + 'item_repo' + 'issue_number'. Each entry may include 'updated_field'; otherwise the top-level 'updated_field' applies. Limit: 100 items per call. (object[], optional)
   - `iteration_duration`: Duration in days for iterations of the field (e.g. 7 for weekly, 14 for bi-weekly). Required for 'create_iteration_field' method. (number, optional)
   - `iterations`: Custom iterations for 'create_iteration_field' method. Only set this when you need iterations with varying durations, breaks between them, or specific titles. Otherwise omit it: GitHub auto-creates three iterations of 'iteration_duration' days starting on 'start_date', which is the right choice for most cases. (object[], optional)
   - `method`: The method to execute (string, required)

pkg/github/__toolsnaps__/projects_write.snap

@@ -41,35 +41,71 @@
         "type": "string"
       },
       "items": {
-        "description": "The set of items to update. Required for 'update_project_items'. Each entry references an existing item by exactly one of: 'node_id' (the item's GraphQL node ID, e.g. as returned by 'list_project_items' or 'add_project_item'), 'item_id' (the numeric project item ID), or (item_owner + item_repo + issue_number). Each entry may optionally include its own 'updated_field'; if omitted, the top-level 'updated_field' is applied. Limit: 100 items per call.",
+        "description": "The items to update. Required for 'update_project_items'. Each entry must match exactly one reference variant: 'node_id', numeric 'item_id', or 'item_owner' + 'item_repo' + 'issue_number'. Each entry may include 'updated_field'; otherwise the top-level 'updated_field' applies. Limit: 100 items per call.",
         "items": {
-          "additionalProperties": false,
-          "properties": {
-            "issue_number": {
-              "description": "Issue number used to resolve the project item together with item_owner and item_repo.",
-              "type": "integer"
-            },
-            "item_id": {
-              "description": "The project item ID. Provide exactly one of node_id, item_id, or (item_owner + item_repo + issue_number).",
-              "type": "integer"
-            },
-            "item_owner": {
-              "description": "Owner of the repository containing the issue. Combine with item_repo and issue_number to resolve the item.",
-              "type": "string"
-            },
-            "item_repo": {
-              "description": "Repository containing the issue. Combine with item_owner and issue_number to resolve the item.",
-              "type": "string"
+          "oneOf": [
+            {
+              "additionalProperties": false,
+              "properties": {
+                "node_id": {
+                  "description": "The project item's GraphQL node ID, as returned by 'list_project_items' or 'add_project_item'.",
+                  "type": "string"
+                },
+                "updated_field": {
+                  "description": "Per-item field update. Overrides the top-level 'updated_field'. Same shape as the top-level 'updated_field'.",
+                  "type": "object"
+                }
+              },
+              "required": [
+                "node_id"
+              ],
+              "type": "object"
             },
-            "node_id": {
-              "description": "The project item's GraphQL node ID. Provide exactly one of node_id, item_id, or (item_owner + item_repo + issue_number).",
-              "type": "string"
+            {
+              "additionalProperties": false,
+              "properties": {
+                "item_id": {
+                  "description": "The numeric project item ID.",
+                  "type": "integer"
+                },
+                "updated_field": {
+                  "description": "Per-item field update. Overrides the top-level 'updated_field'. Same shape as the top-level 'updated_field'.",
+                  "type": "object"
+                }
+              },
+              "required": [
+                "item_id"
+              ],
+              "type": "object"
             },
-            "updated_field": {
-              "description": "Per-item field update. Overrides the top-level 'updated_field'. Same shape as the top-level 'updated_field'.",
+            {
+              "additionalProperties": false,
+              "properties": {
+                "issue_number": {
+                  "description": "Issue number used to resolve the project item.",
+                  "type": "integer"
+                },
+                "item_owner": {
+                  "description": "Owner of the repository containing the issue.",
+                  "type": "string"
+                },
+                "item_repo": {
+                  "description": "Repository containing the issue.",
+                  "type": "string"
+                },
+                "updated_field": {
+                  "description": "Per-item field update. Overrides the top-level 'updated_field'. Same shape as the top-level 'updated_field'.",
+                  "type": "object"
+                }
+              },
+              "required": [
+                "item_owner",
+                "item_repo",
+                "issue_number"
+              ],
               "type": "object"
             }
-          },
+          ],
           "type": "object"
         },
         "type": "array"

pkg/github/projects.go

@@ -32,10 +32,7 @@ const (
 	ProjectStatusUpdateCreateFailedError = "failed to create project status update"
 	ProjectResolveIDFailedError          = "failed to resolve project ID"
 	MaxProjectsPerPage                   = 50
-	// MaxProjectItemsPerBatch caps the number of items processed in a single
-	// update_project_items call. This keeps a batch bounded, prevents runaway
-	// resolution costs, and matches the practical scale of typical triage sweeps.
-	MaxProjectItemsPerBatch = 100
+	maxProjectItemsPerBatch              = 100
 )
 
 // Method constants for consolidated project tools
@@ -495,6 +492,54 @@ Use this tool to get details about individual projects, project fields, and proj
 	return tool
 }
 
+func updateProjectItemsItemSchema() *jsonschema.Schema {
+	updatedField := &jsonschema.Schema{
+		Type:        "object",
+		Description: "Per-item field update. Overrides the top-level 'updated_field'. Same shape as the top-level 'updated_field'.",
+	}
+	variant := func(required []string, properties map[string]*jsonschema.Schema) *jsonschema.Schema {
+		properties["updated_field"] = updatedField
+		return &jsonschema.Schema{
+			Type:                 "object",
+			AdditionalProperties: &jsonschema.Schema{Not: &jsonschema.Schema{}},
+			Properties:           properties,
+			Required:             required,
+		}
+	}
+
+	return &jsonschema.Schema{
+		Type: "object",
+		OneOf: []*jsonschema.Schema{
+			variant([]string{"node_id"}, map[string]*jsonschema.Schema{
+				"node_id": {
+					Type:        "string",
+					Description: "The project item's GraphQL node ID, as returned by 'list_project_items' or 'add_project_item'.",
+				},
+			}),
+			variant([]string{"item_id"}, map[string]*jsonschema.Schema{
+				"item_id": {
+					Type:        "integer",
+					Description: "The numeric project item ID.",
+				},
+			}),
+			variant([]string{"item_owner", "item_repo", "issue_number"}, map[string]*jsonschema.Schema{
+				"item_owner": {
+					Type:        "string",
+					Description: "Owner of the repository containing the issue.",
+				},
+				"item_repo": {
+					Type:        "string",
+					Description: "Repository containing the issue.",
+				},
+				"issue_number": {
+					Type:        "integer",
+					Description: "Issue number used to resolve the project item.",
+				},
+			}),
+		},
+	}
+}
+
 // ProjectsWrite returns the tool and handler for modifying GitHub Projects resources.
 func ProjectsWrite(t translations.TranslationHelperFunc) inventory.ServerTool {
 	tool := NewTool(
@@ -571,37 +616,8 @@ func ProjectsWrite(t translations.TranslationHelperFunc) inventory.ServerTool {
 					},
 					"items": {
 						Type:        "array",
-						Description: "The set of items to update. Required for 'update_project_items'. Each entry references an existing item by exactly one of: 'node_id' (the item's GraphQL node ID, e.g. as returned by 'list_project_items' or 'add_project_item'), 'item_id' (the numeric project item ID), or (item_owner + item_repo + issue_number). Each entry may optionally include its own 'updated_field'; if omitted, the top-level 'updated_field' is applied. Limit: " + strconv.Itoa(MaxProjectItemsPerBatch) + " items per call.",
-						Items: &jsonschema.Schema{
-							Type:                 "object",
-							AdditionalProperties: &jsonschema.Schema{Not: &jsonschema.Schema{}},
-							Properties: map[string]*jsonschema.Schema{
-								"node_id": {
-									Type:        "string",
-									Description: "The project item's GraphQL node ID. Provide exactly one of node_id, item_id, or (item_owner + item_repo + issue_number).",
-								},
-								"item_id": {
-									Type:        "integer",
-									Description: "The project item ID. Provide exactly one of node_id, item_id, or (item_owner + item_repo + issue_number).",
-								},
-								"item_owner": {
-									Type:        "string",
-									Description: "Owner of the repository containing the issue. Combine with item_repo and issue_number to resolve the item.",
-								},
-								"item_repo": {
-									Type:        "string",
-									Description: "Repository containing the issue. Combine with item_owner and issue_number to resolve the item.",
-								},
-								"issue_number": {
-									Type:        "integer",
-									Description: "Issue number used to resolve the project item together with item_owner and item_repo.",
-								},
-								"updated_field": {
-									Type:        "object",
-									Description: "Per-item field update. Overrides the top-level 'updated_field'. Same shape as the top-level 'updated_field'.",
-								},
-							},
-						},
+						Description: "The items to update. Required for 'update_project_items'. Each entry must match exactly one reference variant: 'node_id', numeric 'item_id', or 'item_owner' + 'item_repo' + 'issue_number'. Each entry may include 'updated_field'; otherwise the top-level 'updated_field' applies. Limit: " + strconv.Itoa(maxProjectItemsPerBatch) + " items per call.",
+						Items:       updateProjectItemsItemSchema(),
 					},
 					"body": {
 						Type:        "string",
@@ -1577,9 +1593,6 @@ func buildUpdateProjectItem(ctx context.Context, gqlClient *githubv4.Client, own
 	return buildUpdateProjectItemWithCache(ctx, gqlClient, nil, owner, ownerType, projectNumber, input)
 }
 
-// buildUpdateProjectItemWithCache is the cache-aware variant of buildUpdateProjectItem.
-// When cache is non-nil, name-based field lookups reuse the cache's in-memory index; when
-// nil, each name lookup performs its own GraphQL round trip (single-item behaviour).
 func buildUpdateProjectItemWithCache(ctx context.Context, gqlClient *githubv4.Client, cache *projectFieldsCache, owner, ownerType string, projectNumber int, input map[string]any) (*github.UpdateProjectItemOptions, error) {
 	if input == nil {
 		return nil, fmt.Errorf("updated_field must be an object")

pkg/github/projects_batch.go

@@ -11,13 +11,8 @@ import (
 	"github.com/shurcooL/githubv4"
 )
 
-// batchItemStatus is the tri-state outcome of one item in update_project_items.
-//   - succeeded: the item's alias came back populated, confirming the write.
-//   - failed: a deterministic failure before any mutation was sent (invalid
-//     input, resolution failure, value-conversion failure, duplicate target).
-//   - unknown: a mutation touching this item was not confirmed, or was never
-//     sent after an earlier systemic failure. The pinned client drops
-//     errors[].path, so we don't retry or issue a per-item fallback mutation.
+// Unknown outcomes cannot be attributed or retried safely because the pinned
+// client drops errors[].path.
 type batchItemStatus string
 
 const (
@@ -26,21 +21,15 @@ const (
 	batchItemUnknown   batchItemStatus = "unknown"
 )
 
-// batchItemResult is the per-item outcome returned by update_project_items.
 type batchItemResult struct {
 	Index  int                `json:"index"`
 	Status batchItemStatus    `json:"status"`
 	Item   *batchItemIdentity `json:"item,omitempty"`
 	Error  *batchItemError    `json:"error,omitempty"`
-	// Ref echoes the identifying input for the item so agents can correlate results
-	// with the request even when resolution fails.
+	// Ref preserves the request identity when resolution fails.
 	Ref map[string]any `json:"ref,omitempty"`
 }
 
-// batchItemIdentity is the minimal item identity echoed back for a confirmed
-// write: the mutation response's `projectV2Item { id, fullDatabaseId }`, plus
-// the numeric item_id the request used (when known), so callers can correlate
-// without a follow-up read.
 type batchItemIdentity struct {
 	NodeID         string `json:"node_id,omitempty"`
 	FullDatabaseID string `json:"full_database_id,omitempty"`
@@ -54,21 +43,14 @@ type batchItemError struct {
 	Hint       string `json:"hint,omitempty"`
 }
 
-// resolvedBatchItem is a fully-resolved, validated write, ready to be included
-// in an aliased update or clear mutation.
 type resolvedBatchItem struct {
 	index          int
 	nodeID         string
 	fullDatabaseID int64
 	fieldNodeID    string
-	value          githubv4.ProjectV2FieldValue // unused when this is a clear
+	value          githubv4.ProjectV2FieldValue
 }
 
-// updateProjectItemsBatch handles the update_project_items method. It resolves
-// the project, every distinct field, and every item once up front, then writes
-// via chunked, aliased updateProjectV2ItemFieldValue / clearProjectV2ItemFieldValue
-// GraphQL mutations (pkg/github/projects_batch_mutation.go) instead of one REST
-// PATCH per item.
 func updateProjectItemsBatch(ctx context.Context, client *github.Client, gqlClient *githubv4.Client, owner, ownerType string, projectNumber int, args map[string]any) (*mcp.CallToolResult, any, error) {
 	rawItems, exists := args["items"]
 	if !exists {
@@ -81,8 +63,8 @@ func updateProjectItemsBatch(ctx context.Context, client *github.Client, gqlClie
 	if len(itemsRaw) == 0 {
 		return utils.NewToolResultError("items must contain at least one entry"), nil, nil
 	}
-	if len(itemsRaw) > MaxProjectItemsPerBatch {
-		return utils.NewToolResultError(fmt.Sprintf("items exceeds maximum of %d entries per call (got %d)", MaxProjectItemsPerBatch, len(itemsRaw))), nil, nil
+	if len(itemsRaw) > maxProjectItemsPerBatch {
+		return utils.NewToolResultError(fmt.Sprintf("items exceeds maximum of %d entries per call (got %d)", maxProjectItemsPerBatch, len(itemsRaw))), nil, nil
 	}
 
 	var sharedField map[string]any
@@ -116,17 +98,14 @@ func updateProjectItemsBatch(ctx context.Context, client *github.Client, gqlClie
 		return newUpdateProjectItemsResult(results)
 	}
 
-	// Resolve the project node ID once; every mutation input needs it.
 	projectID, err := resolveProjectNodeID(ctx, gqlClient, owner, ownerType, projectNumber)
 	if err != nil {
 		return utils.NewToolResultError(err.Error()), nil, nil
 	}
 
-	// Resolve every distinct effective field once.
 	cache := newProjectFieldsCache()
 	fieldResolutions := resolveDistinctFields(ctx, gqlClient, cache, owner, ownerType, projectNumber, parsed)
 
-	// Resolve numeric item_id -> node id, deduplicated with bounded concurrency.
 	var numericIDs []int64
 	for _, p := range parsed {
 		if p.err == nil && p.refKind == batchRefItemID {
@@ -135,16 +114,14 @@ func updateProjectItemsBatch(ctx context.Context, client *github.Client, gqlClie
 	}
 	itemIDLookups := resolveItemNodeIDsByNumericID(ctx, client, owner, ownerType, projectNumber, numericIDs)
 
-	// Resolve issue-ref items, deduplicated.
 	issueLookups := resolveIssueRefs(ctx, gqlClient, projectID, parsed)
 
-	// Build the final resolved plan, rejecting duplicate item+field targets.
 	var updates, clears []resolvedBatchItem
-	seenTargets := make(map[string]int) // "nodeID|fieldNodeID" -> first index that claimed it
+	seenTargets := make(map[string]int)
 
 	for i, p := range parsed {
 		if p.err != nil {
-			continue // deterministic parse failure already recorded above
+			continue
 		}
 
 		fr := fieldResolutions[p.fieldKey]
@@ -187,9 +164,7 @@ func updateProjectItemsBatch(ctx context.Context, client *github.Client, gqlClie
 		updates = append(updates, resolvedBatchItem{index: i, nodeID: nodeID, fullDatabaseID: fullDatabaseID, fieldNodeID: fr.field.NodeID, value: value})
 	}
 
-	// Execute update mutations, then clear mutations, in sequential chunks.
-	// Clears never run if the update phase aborted: we do not know whether an
-	// ambiguous failure landed, so we do not risk further writes this call.
+	// Skip clears after an ambiguous update failure because an earlier write may have landed.
 	aborted := executeBatchPartition(ctx, gqlClient, batchMutationUpdate, projectID, updates, results, parsed)
 	if !aborted {
 		executeBatchPartition(ctx, gqlClient, batchMutationClear, projectID, clears, results, parsed)
@@ -232,9 +207,6 @@ func newUpdateProjectItemsResult(results []batchItemResult) (*mcp.CallToolResult
 	return result, nil, nil
 }
 
-// resolveItemReference maps a parsed item's reference to its project item node
-// ID and (when known) numeric full database ID, using the pre-computed lookup
-// tables for the item_id and issue-ref cases.
 func resolveItemReference(p parsedBatchItem, itemIDLookups map[int64]itemLookupResult, issueLookups map[issueRefKey]itemLookupResult) (nodeID string, fullDatabaseID int64, err error) {
 	switch p.refKind {
 	case batchRefNodeID:
@@ -257,12 +229,8 @@ func resolveItemReference(p parsedBatchItem, itemIDLookups map[int64]itemLookupR
 	}
 }
 
-// executeBatchPartition executes a single partition (all updates, or all
-// clears) in sequential chunks of at most batchMutationWireChunkSize. It
-// writes outcomes directly into results (keyed by original index) and returns
-// true if execution was aborted before every item in the partition was
-// attempted, because an earlier chunk's failure looked systemic (transport
-// failure or context cancellation) rather than a per-mutation GraphQL error.
+// Transport, cancellation, or incomplete-data ambiguity stops later chunks;
+// GraphQL response errors do not because populated aliases still confirm writes.
 func executeBatchPartition(ctx context.Context, gqlClient *githubv4.Client, kind batchMutationKind, projectID githubv4.ID, items []resolvedBatchItem, results []batchItemResult, parsed []parsedBatchItem) bool {
 	for start := 0; start < len(items); start += batchMutationWireChunkSize {
 		if ctx.Err() != nil {