fix(run): allow caller-supplied taskUUID instead of always generating

The API supports caller-provided task identifiers but the CLI rejected
taskUUID as a reserved field. Demote taskUUID from Protected to
auto-only so it is still excluded from completions and validation but
no longer blocked as a key=value argument. If the caller supplies an
invalid UUID, Run returns an error before submitting.

Closes RUN-10706

Author: danmrichards

internal/api/client.go

@@ -222,8 +222,18 @@ func (c *Client) Run(ctx context.Context, model string, args []string, opts RunO
 		payload[fieldDeliveryMethod] = deliveryMethod
 	}
 
-	// Inject system fields.
-	taskUUID := uuid.New()
+	// Inject system fields. Use a caller-supplied taskUUID if provided, otherwise generate.
+	var taskUUID uuid.UUID
+	if raw, ok := payload[fieldTaskUUID]; ok {
+		s, _ := raw.(string)
+		parsed, err := uuid.Parse(s)
+		if err != nil {
+			return nil, fmt.Errorf("taskUUID: invalid UUID %q: %w", s, err)
+		}
+		taskUUID = parsed
+	} else {
+		taskUUID = uuid.New()
+	}
 	payload[fieldTaskType] = taskType
 	payload[fieldTaskUUID] = taskUUID
 

internal/api/run_test.go

@@ -401,3 +401,66 @@ func TestClientRun_RawArgs_InvalidKV(t *testing.T) {
 		t.Errorf("expected 0 transport calls, got %d", mock.callCount)
 	}
 }
+
+// TestClientRun_UserProvidedTaskUUID: a caller-supplied taskUUID must be forwarded
+// to the API unchanged instead of being overwritten with a new UUID.
+func TestClientRun_UserProvidedTaskUUID(t *testing.T) {
+	const wantUUID = "d58cbacc-bed6-413e-9e4a-b118e4d84035"
+
+	srv := inferenceSchemaServer(t, requestSchemaWithTaskType("imageInference", "sync"))
+
+	mock := &mockTransport{
+		responses: []mockResponse{
+			{data: []json.RawMessage{successItem(t, nil)}},
+		},
+	}
+
+	c := NewClient(mock, slog.Default())
+	c.schemaBaseURLOverride = srv.URL + "/"
+
+	_, err := c.Run(context.Background(), testModelAIR, []string{"taskUUID=" + wantUUID}, RunOptions{})
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+
+	if len(mock.captured) == 0 {
+		t.Fatal("no transport calls captured")
+	}
+	taskBytes, err := json.Marshal(mock.captured[0][0])
+	if err != nil {
+		t.Fatalf("marshal captured task: %v", err)
+	}
+	var payload map[string]any
+	if err := json.Unmarshal(taskBytes, &payload); err != nil {
+		t.Fatalf("unmarshal captured task: %v", err)
+	}
+	got, ok := payload["taskUUID"]
+	if !ok {
+		t.Fatal("taskUUID not present in submitted payload")
+	}
+	if s, _ := got.(string); s != wantUUID {
+		t.Errorf("taskUUID: got %q, want %q", s, wantUUID)
+	}
+}
+
+// TestClientRun_UserProvidedTaskUUID_Invalid: an invalid UUID value must return
+// an error before any transport call is made.
+func TestClientRun_UserProvidedTaskUUID_Invalid(t *testing.T) {
+	srv := inferenceSchemaServer(t, requestSchemaWithTaskType("imageInference", "sync"))
+
+	mock := &mockTransport{}
+
+	c := NewClient(mock, slog.Default())
+	c.schemaBaseURLOverride = srv.URL + "/"
+
+	_, err := c.Run(context.Background(), testModelAIR, []string{"taskUUID=not-a-uuid"}, RunOptions{})
+	if err == nil {
+		t.Fatal("expected error for invalid taskUUID, got nil")
+	}
+	if !strings.Contains(err.Error(), "taskUUID") {
+		t.Errorf("expected error to mention %q, got: %v", "taskUUID", err)
+	}
+	if mock.callCount != 0 {
+		t.Errorf("expected 0 transport calls, got %d", mock.callCount)
+	}
+}

internal/schema/schema.go

@@ -106,8 +106,7 @@ var ManagedFields = map[string]ManagedField{
 		Hint:      "use the --task-type flag instead",
 	},
 	"taskUUID": {
-		Protected: true,
-		Hint:      "this field is system-generated and cannot be set manually",
+		Protected: false,
 	},
 	"deliveryMethod": {
 		Protected: false,

internal/schema/schema_test.go

@@ -629,10 +629,10 @@ func TestIsProtected_ModelRejected(t *testing.T) {
 	}
 }
 
-func TestIsProtected_TaskUUIDRejected(t *testing.T) {
+func TestIsProtected_TaskUUIDAllowed(t *testing.T) {
 	_, blocked := schema.IsProtected("taskUUID")
-	if !blocked {
-		t.Error("expected taskUUID to be protected")
+	if blocked {
+		t.Error("taskUUID must not be protected — callers may supply their own task identifier")
 	}
 }